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This manual, formerly titled / 
am : 


» 1s now titled MVS/Extended 


emn~ 


This publication provides information for system programmers 
about MVS/Extended Architecture Data Facility Product, and how 
to modify and extend the data management capabilities of the 
operating system. 


This publication contains the following chapters and appendixes: 


e Chapter 1, "Managing the Volume Table of Contents (VTOC)" on 
page 1, defines and discusses the structure of the VTOC and 
VTOC index, and the use of system macros to read a data set 


control block, rename a data set, or delete a data set from 
the VTOC. 


e Chapter 2, "Executing Your Own Channel Programs CEXCP)™ on 
page 36, defines and discusses the use of the EXCP macro to 
control the organization of data based on device 
characteristics with your own channel programs. 


e Chapter 3, "Reading from and Writing to Direct Access 
Devices (XDAP)"™ on page 75, defines and discusses the use of 
the XDAP macro to read, verify, and update blocks without 
uSing an access method. 


e Chapter G4, "Password Protecting Data Sets™ on page 84, 
defines and discusses system password protection and how to 
create and maintain the PASSWORD data set. 


e Chapter 5, "Exit Routines™ on page 96, defines and discusses 
some of the IBM-supplied exits for installation-written 
routines and authorized user programs. 


@ Chapter 6, "System Macro Instructions" on page 110, defines 
and discusses the system macros used to refer to, validate, 
and modify system data areas. 


e Chapter 7, "Maintaining SYS1.IMAGELIB"™ on page 156, defines 
and discusses adding a UCS or FCB image to the system image 
library, and maintaining the UCS image tables. ) 


e Chapter 8, "JES2 Support for the IBM 1403, 3203 Model 5, and 
3211 Printers™ on page 174, defines and discusses JES2 
support for UCS alias names and the 3211 indexing feature. 


° Chapter 9, "CATALOG, SCRATCH, and RENAME Dummy Modules" on 
page 176, defines and discusses the dummy modules for 
CATALOG, SCRATCH, and RENAME, and how to replace them. 


® Chapter 10, "Specifying Buffer Numbers for DASD Data Sets” . 
on page 177, defines and discusses the performance 
considerations when using the BUFNO keyword and. 
subparameter. 


e Appendix A, "CVAF - VTOC Access Macros" on page 178, defines 
and discusses the format of the VTOC access macros: 
CVAFDIR, CVAFDSM, 


e Appendix B, "Examples of VTOC Access Macros"™ on page 196, 


defines and discusses examples of using the VTOC access 
macros in your programs. | 
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y Appendix C, "VTOC Index Error Message and Associated Codes" 
on page 221, defines and discusses the error message and 


fener issued by the Common VTOC Access Facility fo 


e Appendix D, “Example of an OPEN Installation Exit Module™ on 
page 225, defines and discusses a sample program listing for. 
IFGOEXOB, the installation-written exit routine that takes 
control during OPEN for a DCB. 
PREREQUISITE KNOWLEDGE 


In order to use this book efficiently, you should be familiar 
with the following topics: 


e Assembler language | 
e Standard program linkage conventions 
6 The utility programs IEHLIST and IEHPROGM 


® Data management access methods and macro instructions 


REQUIRED PUBLICATIONS 


You should be familiar with the information presented in the 
following publications: 





Reference, "6c26=4037, and As 
tide, GC26-4036, contain more information on 
ceding in escenble- language. 





. = rise = A » = > é il L s oI : ee 
Supervisor Services and Macro Instructions, GC28-1154, —_— 
contains a description of standard linkage conventions. Ne 


e MVS7Extended A aF 2 Data Admini ] LLiti 
GC26-4018, daccri bes how to use LEHLIST to Roan tesn “the . 
VTOC, and IEHPROGM to protect data sets. 





MVS7 - 

GC26- 4013, and fis Extended Architecture Data 
: J Re ence, GC26-4014, 

contain catermatian on using acceae mathode= and macro 

instructions to do input and output. 





Specific prerequisite reading is listed at the beginning of some 
chapters, as it relates to the particular topic. 


Within the text, references are made to the publications listed 
in the table below. 


Short Title 3 | 
(as it appears | 
in the text) Publication Title Order Number 


Access Method j GC26-4019 
Services Reference Integrated Catalog 


GC26-4075 
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Short Title 

(as it appears 

in the text) Publication Title Order Number 
Assembler H V2 Assembler _H Version 2 93C26-4036 
Application j j j : 

Programming: Guide Guide 





f 
t 
t 
i 
| 
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Assembler H V2 Assembler H Version 2 GC26-4037 
Application Application Programming: 
Programming: 

Language Reference 


Catalog 
Administration Guide 
Checkpoint/Restart 
User's Guide 
Conversion Notebook 





GC26-4041 


GC26-4012 


GC28-1143 


SY26-3929 


CVAF Diagnosis 
Reference 


DADSM and CVAF 
Diagnosis Guide 


— DADSM Diagnosis MV5ZExtended Architecture SY26-3904 
( ‘ Reference | DADSM Diagnosis Reference 

s Data Administration MVS/ZExtended Architecture GC26-4013 
Guide Data Administration Guide 


Data Administration: MVS/Extended Architecture GC26-4014 
Macro Instruction Data Administration: Macro 
Reference Instruction Reference 

MVS/Extended Architecture 

Debugging Handbook 


SY26-3896 





Debugging Handbook LC28-11642 
ook, LC28-1165 
Volumes 1 through 5 


LC28-1166 
LC28-1167 
LC28-1168 





Device Support Device Support Facilities GC35-0033 
Facilities User's User's Guide and Reference 

Guide and Reference | 

IBM System/370 XA IBM System/370 Extended SA22-7085 
Principles of i i 

Operation j 


IBM 2821 Control IBM 2821 Control Unit GA24-33512 | 


: 
Ht 


Unit Component Component Description 
Description 
Note: 


i All five volumes may be ordered under one order number, 
LBOF-1015. 
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Short Title 
(as it appears 
in the text) 


IBM 3203 Printer 
Component | 

Description and 
Operator's Guide 


IBM 3211 Printer, 
3216 Interchangeable 
Train Cartridge, and 
3811 Printer Control 
Unit Component 

Description and 
Operator's Guide 


IBM 3800 Printing 
Subsystem 
Programmer's Guide 


Order Number 
GA33-1515 

















GA24-3543 


GC26-3846 


Initialization and GC28-1149 


Tuning ! 
and Tuning 


Linkage Editor and MVSZExtended Architecture GC26-4011 . 
Loader User's Guide j 3 
pave | Ree 
ayvstem Programming 
: : : 
MVS7Extended Architecture 
p : 
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Supervisor Services GC28-1154 
and Macro 
Instructions 


2ystem Programming 
















System Logic Library S/ e LY28-1234 
System Logic Library: (Part 1) 
Volume 8 of 17, Parts 1 LY28-1235 
and 2 CI0S) €Part 2) 
















GC28-1150 
GC28-1151 






System Macros and 
Facilities 






Library: System Macros and 
facilities, Volumes 1 and 


System Messages MVSZExtended Architecture GC28-1376 
Message Library: System GC28~-1377 
Messages 


System Modifications 






/ i 
, Volunes l and 2 
MVS7Extended Architecture GC28-1152 
2ystem Programming — 
Library: System 
Modifications 
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Short Title 


(as it appears 
in the text) 


TSO Command Language 
Reference 


TSO/E Command 
Language Reference 
TSO/E Data Areas 


Utilities 


VSAM Administration: 





Order 
Number 


GC28-0646 


Publication Title 

MVS Extended Architecture 
I50 Command Language 
Reference COS/VS2 TSO 
Command Language 
Reference, as updated by 
Supplement SD23-0259 for 
MVS/XA) 


$C28-1134 


LYB8~-1119 


O/ (plus 
Supplement LDB3-02764) 


GC26-4018 


GC26-4016 


Macro Instruction 
Reference 


| 





NOTATIONAL CONVENTIONS 


eas, A uniform system of notation describes the format of data 
- management macro instructions. This notation is not part of the 
| language; it simply provides a basis for describing the 
structure of the commands. 


The command format illustrations in this book use the following 
conventions: 


e Brackets [ 1] indicate an optional parameter. 


e Braces {€ } indicate a choice of entry; unless a default is 
indicated, you must choose one of the entries. 


e Items separated by a vertical bar (|) represent alternative 
items. No more than one of these items may be selected. 


@ An ellipsis (...) indicates that multiple entries of the 
type immediately preceding the ellipsis are allowed. 


e Other punctuation (Cparentheses, commas, spaces, and so 
MAb must be entered as shown. A space is indicated by a 
ank. 


e BOLDFACE type indicates the exact characters to be entered, 
except as described in the bullets above. Such items must 
be entered exactly as illustrated. 


@ Lowercase underscored type specifies fields to be supplied 
by the user. 


e BOLDFACE UNDERSCORED type indicates a default option. If 


the parameter is omitted, the underscored value is assumed. 


e Parentheses € ) must enclose subfields if more than one is 
specified. If only one subfield is specified, you may omit 
the parentheses. . 
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ADDRESS AND REGISTER CONVENTIONS 


The following describes the meaning of each notation used to 
show how an. operand can be coded: 


vill 


(0) 


(1) 


The operand can be any valid assembler-language symbol. 


General register 0 can be used as an operand. When used as 
an operand in a macro instruction, the register must be 
specified as the decimal digit 0 enclosed in parentheses as 
shown above. 


General register 1 can be used aS an operand. When used as 
an operand in a macro instruction, the register must be 
specified as the decimal digit 1 enclosed in parentheses as 
shown above. When you use register 1, the instruction that 
loads it is not included in the macro expansion. 


(2-12) 


The operand specified can be any of the general registers 2 
through 12. All registers as operands must be coded in 
parentheses; for example, if register 3 is coded, it is 
coded as (3). When one of the registers 2 through 12 is 
used, it can be coded as a decimal digit, symbol Cequated 
to a decimal digit), or an expression that results in a 
value of 2 through 12. 


Ss 

The operand can be specified as any valid 
assembler-language RX-type address. The following shows 
examples of each valid RX-type address: 


Name Operation Operand 


ALPHA] 1,39¢04,10) 
ALPHA2 REG1,39(4, TEND 
BETA] 2,ZETAC4) 

BETA2 | REG2, ZETACREG4) 
GAMMAI 2,ZETA 

GAMMA2 REGZ,ZETA 
GAMMAS3 2,=F'1000' 
LAMBDA] 3,20¢,5) 


Sccerccece 


Both ALPHA instructions specify explicit addresses; REGI1 
and TEN have been defined as absolute symbols. Both BETA 
instructions specify implied addresses, and both use index 
registers. Indexing is omitted from the GAMMA 
instructions. GAMMAl1 and GAMMA2 specify implied addresses. 
The second operand of GAMMA3 is a literal. LAMBDA] 
specifies an explicit address with no indexing. 


The operand can be specified as any address that can be 
written as a valid assembler-language A-type address | 
constant. An A-type address constant can be written as an 
absolute value, a relocatable symbol, or relocatable 
expression. Operands that require an A-type address are 
inserted into an A-type address constant during the macro 
expansion process. For more details about A-type address 
constants, see j j j 


absexp 


The operand can be an absolute value or expression. An 
absolute expression can be an absolute term or an | 
arithmetic combination of absolute terms. An absolute term 
can be a nonrelocatable symbol, a self-defining term, or 
the length attribute reference. For more details about 
absolute expressions, see j j j 
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relexp 


= The operand can be a relocatable symbol or expression. A 
=~ relocatable symbol or expression is one whose value changes 
by n if the program where it appears is relocated n bytes 
away from its originally assigned area of storage. For 
more details about relocatable symbols and expressions, see 
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| NEW PROGRAMMING SUPPORT 


| NEW DEVICE SUPPORT 


| SERVICE CHANGES 


EAS 


Support has been added for the conversion to ISO/ANSI/FIPS 
arto 3 tape labels, a new function of the WITOR installation 
exit. | 
Support has been added for 3480 block count checking, which 
compares the 3480 block count with the block count maintained by 
the system at end-of-volume. 


Support has been added for the 3480 label processing PTF, which 
improves 3480 performance. 


Support has been added for the 3380 Mod AD4, BDG, AE4, and BEG. 
Support has been added for the 3880 Model 21 and Model 23. 
Support has been added for the 3480 Magnetic Tape Subsystem. 


Information has been added, corrected, or deleted to reflect 
technical service changes. 


RESTRUCTURE AND UPDATING 


This manual, formerly titled / 


ent, is now titled MVS/7Extended 
Except for the updates noted below, the text of this manual is 


substantially the same as in Release 1.0. The following changes 
have been made: 


e The Preface has been rewritten for stylistic consistency 
with the other MVS/XA documentation. 


e The former Chapter 1, "Using Catalog Management Macro 
Instructions,™ has been moved to ini } 
ide, and succeeding chapters have been renumbered. 


e The “"old™ Appendix C, "Return Codes from VTOC Access 
Macros," has been combined with Appendix A, and the 
"Overviews" of the VTOC Access Macros formerly in Chapter 2 
are now included in Appendix A. 


@ Chapter 7, "Maintaining SYS1.IMAGELIB,™ has been rewritten 
for ease of use. 


° References to other manuals have been updated to reflect 
title changes for Release 1.2. 

















@ Service changes have been made throughout the manual, and 
are indicated in the text by revision bars. 


C 


PROGRAMMING SUPPORT 
Descriptions of the following have been added: 
e ISO/ANSI/FIPS GDG password protection 
e The new DADSM macro REALLOC, and REALLOC return codes 
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The direct access device storage management CDADSM) routines 
control allocation of space on direct access volumes through the 
volume table of contents CVTOC) of that volume, and through the 
VTOC index if one exists. This chapter gives an overview of the 
VTOC and the VTOC index and discusses how to use system macros 
to access the VTOC and VTQC index. 


The VTOC is a data set on a direct access volume that describes 
the contents of that volume. It resides in a single extent 
(that is, it is a continuous data set) anywhere on the volume 
after cylinder 0, track 0. Its address is located in the 
VOLVTOC field of the standard volume label (see Figure 1). 


Standard Volume Label 


11(B) 





VOLVTOC (10 bytes) 
CCHHR of first 
record in VTOC 
\ 
\ | ye 
‘ / 
\ ff 
‘ vA 
4 / 
~ / 
‘ 7 
. a A 
CylinderO \ 
Track 0 4 


Record Record} Record 
2 3 


VTOC Data Set 


(Can be located anywhere 
Record Record on the volume after 
1 , es cylinder 0, track 0.) 


Figure 1. Locating the Volume Table of Contents (CVTOC) 
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The VTOC is composed of 140-byte!? data set control blocks 

(DSCBs) that correspond either to a data set or VSAM data space as 
currently residing on the volume, or to contiguous, unassigned < 
tracks on the volume. DSCBs for data sets or data spaces ‘/ 
describe their characteristics. DSCBs for contiguous, ass 

unassigned tracks indicate their location. 


DATA SET CONTROL BLOCK (DSCB) FORMAT TYPES 


The VTOC has seven different kinds of DSCBs. This section lists 
the different Kinds of DSCBs, what they are used for, how many 
exist on a volume, and how they are found. 


The first record in every VTOC is the VTOC Cformat-4) DSCB that 
describes (1) the device that the volume resides on, (2) the 
attributes of the volume itself, and (3) the size and contents 
of the VTOC data set itself. | 


The format-4 DSCB is followed by a free-space (format-5) DSCB 
that, for a nonindexed VTOC, lists the extents on the volume 
that have not been allocated to a data set or VSAM data space. 
Each format-5 DSCB contains 26 extents. If there are more than 
26 available extents on the volume, another format-5 DSCB will 
be built for every 26 extents. The format-5 DSCBs are chained, 
using the last field of each format-5 DSCB. An indexed VTOC 
does not use format-5 DSCBs for describing free space; however, 
one empty format-5 DSCB is provided to allow a basis for 
converting back to a nonindexed VTOC. 


The third and subsequent DSCBs in the VTOC do not have any 
prescribed sequence. 


A data set or VSAM data space is defined by one or more DSCBs in 
the VTOC of each volume on which it resides. The number of 
DSCBs needed to define a data set or VSAM data space is 
determined by (1) the organization of the data set CISAM data 
sets need a format-2 DSCB to describe the index) and (2) the 
number of extents the data set or VSAM data space occupies (a 
format-3 DSCB is needed to describe the 4th through the 16th 
extents; additional format-3 DSCBs may be required to describe 
the extents for a VSAM data set cataloged in an integrated 
catalog facility catalog). Figure 2 on page 5 shows the general 
makeup of a VTOC and the DSCBs needed = define two types of 
data sets CISAM and non-ISAM). 


ae: we 


Ne 


Data set A Cin Figure 2 on page 5) is an ISAM data set; three 
DSCBs, a format-l, format~-2, and format-3, are identified. Data 
sets B, C, and D could be sequential, partitioned, or direct 
data sets or they could be VSAM data spaces. Data set B has 
more than three extents and therefore requires both a format-l 
and a format-3 DSCB. 


Data sets C and D have three or fewer extents and need only a 
format-1l DSCB. The format-6 DSCB, pointed to by the format-4 
DSCB, is used to Keep track of the extents allocated in order to 
be shared by two or more data sets (split-cylinder data sets). 
For example, if data sets C and D share an extent made up of one 
or more cylinders, this extent would be described in the 
format-6 DSCB. Note that split-cylinder data sets cannot be 
allocated, but existing split-cylinder data sets can still be 
processed. 





1 The 140-bytes are defined as a 44-byte key portion followed 
by a 96-byte data portion. You may make references to the 
logical 140-byte DSCB or to either of its parts. 
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Format-0 DSCB 


Format-1 DSCB 


Format-2 DSCB 


Format-3 DSCB 








NAME: Free VTOC Record 


FUNCTION: Describes an unused record in the VTOC (contains 140 
bytes of binary zeros). To delete a DSCB from the VTOC, a 
format-0 DSCB is written over it. 


HOW MANY: One for every unused 140-byte record on the VTOC. 

The DSGDSREC field of the format-4% DSCB is a count of the number 
of format-0 DSCBs on the VTOC. This field is not maintained for 
an indexed VTOC. ; 


HOW FOUND: Search on Key equal to X'00' Csometimes X'00000000') 
for a nonindexed VTOC; for an indexed VTOC, the VTOC map of 
DSCBs is used to find a format-0 DSCB. 


NAME: Identifier 


FUNCTION: Describes the first three extents of a data set or 
VSAM data space. 


HOW MANY: One for every data set or data space on the volume, 
except the VTOC. 


HOW FOUND: Search on Key equal to the data set name. For an 
Th tae ana a CCHHR pointer for each data set name is in the 
index. 


NAME: Index 
FUNCTION: Describes the indexes of an ISAM data set. 


HOW MANY: One for every ISAM data set (for a multivolume ISAM 
data set, a format-2 DSCB exists only on the first volume). 


HOW FOUND: Chained from a format-1 DSCB that represents the 
data set. 


NAME: Extension 


FUNCTION: Describes the 4th through 16th extents of a data set 
or VSAM data space. Data sets and VSAM data spaces are 
restricted to 16 extents per volume. VSAM data sets cataloged 
in an ICF catalog may be extended to a maximum of 123 extents, 
in which case there may be as many as ten format-3 DSCBs. 


HOW MANY: One for each data set or VSAM data space on the 
volume that has more than three extents. There may be as many 
as ten for a VSAM data set cataloged in an ICF catalog. 


HOW FOUND: Chained from a format-2 or a format-1 DSCB that 
represents the data set or VSAM data space. In the case of a 
VSAM data set cataloged in an ICF catalog, the chain may be from 
a preceding format-3 DSCB. | 
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Format-4 DSCB 


Format-5 DSCB 


Format-6 DSCB 


NAME: VTOC 

FUNCTION: Describes the extent and contents of the VTOC and 
provides volume and device characteristics. If the VTOC is 
indexed, certain fields of this DSCB are not maintained by 
DADSM. See "Structure of an Indexed VTOC." 

HOW MANY: One on each volume. 


HOW FOUND: VOLVTOC field of the standard volume label contains 
its address. It is always the first record in the VTOC. 


NAME: Free Space 


FUNCTION: On a nonindexed VTOC, describes the space on a volume 


that has not been allocated to a data set or to a VSAM data 
space Cavailable space). For an indexed VTOC, format-5 is zero, 


and the volume pack space map describes the available space. 


HOW MANY: One for every 26 noncontiguous extents of available 
space on the volume for a nonindexed VTOC; for an indexed VTOC, 
there is only one. 


HOW FOUND: The first format-5 DSCB on the volume is always the 
second DSCB of the VTOC. If there is more than one format-5 
DSCB, it will be chained from the previous format-5 DSCB via the 
DS5SPTRDS field of each format-5 DSCB. 


NAME: Shared Extent 


FUNCTION: Describes the extents shared by two or more data sets 
(split-cylinder extents). 


HOW MANY: One for every 26 split-cylinder extents on the VTQC. 


HOW FOUND: The address of the first format-6 DSCB is contained 
in the DSGF6PTR field of the format-4 DSCB. If there is more 
than one format-6 DSCB on the volume, it will be chained from 
the previous format-6 DSCB via the DSG6GPTRDS field of the 
format-6 DSCB. 


ALLOCATING AND RELEASING SPACE 


The DADSM allocate and extend routines assign tracks and 
cylinders on direct access volumes for new data sets and VSAM 
data spaces. additional space for a data set or VSAM data space 
that has already exceeded its original, primary allocation. The 
DADSM scratch and partial release routines are used to release 
space that is no longer needed ona direct access volume. 


The DADSM routines allocate and release space by adding, 
deleting, and modifying the DSCBs. When space 1s needed on a 
volume, the allocate routines search the appropriate DSCBs for 
enough contiguous, available tracks to satisfy the request. If 
there are not enough contiguous tracks, the request is filled, 
uSing as many as five noncontiguous groups of free tracks. The 
ale DSCBs are modified to reflect the assignment of the 
racks 


When space is released, the scratch routines free the DSCBs of 
the deleted data set or data space. For a nonindexed VTOC, to 
indicate that the tracks containing the affected data set or 
data space can be reallocated, a free space (format-5) DSCB is 
built Cor modified if existent). For an indexed VTOC, the index 
is updated. 
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Standard Volume Label 


11(B) 
VOLVTOC 





field 


VTOC Data Set 


Format-4 DSCB First FS DSCB 


Description of Description of 
device, volume, 26 available 
and the VTOC extents 

extent 


Format-6 DSCB 


Description of 
as many as 26 
shared-cylinder 





Data Set A 





Data Set B 
Format-1 DSCB Gy 






Description of 
the data set yy 
its first 3 essenty 











Data Set C 


Next FS DSCB 


Description of 
as many as 26 
available exents 





extents 


Data Set D 


Format-1 DSCBYY 


Description of 
the data set and 





DSCB for an ISAM 
data set (Data Set A) 





Note: 


Figure 2. 





DSCB for a non-ISAM 
data set (Data Sets B,C, D) 
or a VSAM data space 


Empty boxes in the VTOC data set represent free VTOC Records (Format-0 DSCBs) 


Contents of VTOC-—-DSCBs Describing Data Sets 
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The VTOC index is a physical-sequential data set, residing on oO 
the same volume as the VTOC. It contains an index of data set ‘ y/ 
names of format-l DSCBs in the VTOC and free space information. : 
The index is searched instead of the hardware keys. 


The VTOC index is optional. You may build it when you 
initialize the volume, or for an existing VTOC Cwith the volume 
‘online or offline). You may subsequently inactivate it Conline 
A a so that the VTOC is processed without using the 
index. | | 


Each VTOC index is formatted by Device Support Facilities with 
physical blocks 2048 bytes in length. These physical blocks are 
the VTOC index records (VIRs), the basic structural units of the 
index. The kind of information they contain depends on the part 
of the index they belong to. 


Several different Kinds of records, each built from one or more 
VIRs, are in a VTOC index: 


e The VTOC index entry record CVIER) that is used to access 
format-1l DSCBs and the format-%4 DSCB 


e The VTOC pack space map (VPSM) that shows what space has 
been allocated ona disk pack 


@ The VTOC index map CVIXM) that shows which VIRs have been 
allocated in the VTOC index 


e The VTOC map of DSCBs CVMDS) that shows which DSCBs have 
been allocated in the VTOC 
AN EXAMPLE OF A VTOC AND ITS INDEX aa 
A format-l DSCB in the VTOC contains the name and extent ee 
information of the VTOC index. The name of the index must be 
™SYS1L .VTOCIX.xxxxxxxx', where "xxxxxxxx' can be anything valid 
in a data set name and is generally the serial number of the 
volume containing the VTOC and its index. The name must be 
unique within the system to avoid ENQ contention. The 
relationship of a VTOC to its index is shown in Figure 3. Each 


of the components of the index 1s discussed separately in the 
following sections. 


VTOC VTOC Index 


Format—-4 DSCB VIXM 

Format-5 DSCB | VPSM 

| VMDS 
Other DSCBs 

VIER 

VIER 

VIER 





















Format-1 DSCB for the VTOC 
Index: SYS1.VTOCIX.nnn 


Other DSCBs 


Figure 3. Relationship of a VTOC to Its Index 
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THE VTOC INDEX ENTRY RECORD (VIER) 
( VIERs have these characteristics: 


e A VIER uses one VIR and contains variable-length index 
entries. The number of VIERS in an index vary depending 
upon the number of data sets on the volume. 


@ VIERs in a VTOC index may be on one or many levels. All 
index entries ina VIER are at the same index level. VIERs 
have a hierarchic relationship. Index entries in 
higher-level VIERs point to lower-level VIERs. Index 
entries in level-one VIERs (those at the lowest level) point 
to format-l DSCBs for data sets on the volume. 


® A higher-level VIER is created when the fourth lower-level 
VIER is created. When that new higher-level VIER is filled 
with pointers to lower-level VIERs, a new VIER at the same 
level is created. Again, when the fourth VIER at the same 
level is created, a VIER at a still higher level is created, 
adding another level to the index. 


Contents of VIER Fields 


Each VIER contains a header and sections (see Figure 4 on 
page 8). The VIER header contains: 


e A field identifying the VTOC index record as a VIER. 
e The relative byte address CRBA) of the VIER. 
@ A pointer to a VIER at the same level Chence, a "horizontal" 


pointer). The VIER pointed to contains index entries whose 
keys are greater than any Key in the pointing VIER. 


( : ¢ The level number (LVL) of this VIER. 
_ ¢ The number (SECNO) of sections (a VIER contains eight 
sections). 


e The length CSECL) of the sections Ceach section is 246 bytes 
in length). 


6 The offsets to the first-used and the last-used eaetione: 
® The 44-byte high key of the VIER. 
Each section contains: 


e An offset to the last entry in the section Cor zero if the 
section is empty) 


e Index entries 
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0(00)  EBCDIC Characters "VIER" 
4004) RBA of This VIER 
8008) | Horizontal Pointer 
12¢0c) Old Horizontal Pointer 
Header 
20¢€14) PTRL SECNO SECL 
24018) Offset to First-Used Section 
28C1C) Offset to Last—-Used Section 
32¢€20) Highest Key in This VIER 
8 Sections 
Containing 
Index 
Entries 


Figure 4. Format of the VTOC Index Entry Record CVIER)D 


Format of a VTOC Index Entry 


The format of an index entry is: 


Name Offset Bytes Description 

VXEFLG 00¢00) 1 Flag byte 

VXEKEYL 01¢€01) 1 Length of the VXEKEY field 
VXEFC 02¢02) 1 Unused 

VXERPTR 03(03) G4 or 5 Record pointer 

VXEKEY 07€07) 1 to 44 Name of a data set, if a 


or level-one VIER; if not, the 
08¢€08) high key in the header of a 
lower-level VIER 


Each index entry contains: 
e A flag byte. 


e A keylength field (containing a value of 1 to 44, depending 
on the length of the data set name). 


e A record pointer (VXERPTR) that is one of the following: 
= In level~one VIERs, the 5-byte CCHHR of the format-l or 


format-4 DSCB that represents the data set whose name is 
the key in the entry 


= In other VIERs, the 4G-byte RBA of the lower-level VIER 
whose high key is the Key in the entry 
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e A key that, for level 1 VIERS, is the data set name, and for 
level 2 or higher VIERs is the high key of a lower-level 
VIER. Trailing blanks. are suppressed in the VTOC index 
entry. 


When a VIER Is Created 


The first level-one VIER is created when the VTOC index is 

created. Subsequent VIERsS are created when a data set name is 
to be added to the VTOC index but the VIER where it should be 
added is full. A new VIER is created in the following manner: 


e A new VIER is allocated. 

® Half of the sections from a full VIER Cthose containing the 
highest keys) are moved into the new VIER, leaving each VIER 
half empty. | 


® The new index entry 1s added to one of the two VIERs, 
depending on its key. — 


A Tree of Linked VIERs 


Figure 5 on page 10 shows how VIERS are related to each other. 
Note that the VIERs (which are simplified here—only the high 
key is shown in the header) form a type of "tree structure."™ 


How to Find a Format-1 DSCB 


In the search for the format-l1 DSCB for a particular data set, 
one path along the tree structure is followed. 


As seen in Figure 4 on page 8, a field in the header of a VIER 
contains the highest key of any index entry in that VIER. 
Beginning with this field in the first high-level VIER, the 
following search logic is used: Is the key of the data set (the 
data set name) lower than or equal to the VIER'’s high key? If 
neither, the test is again applied with the VIER having a 
greater high key pointed to by the horizontal pointer. This 
procedure continues until a VIER is found having a high key that 
1s greater than or equal to the key of the data set. 

Comparisons are then made witn the entries in the VIER's 
sections. Eventually, an entry is found with a Key greater than 
or equal to the data set key. This entry points to a VIER at 
the next-lower level. 


The search proceeds to successively ewan Vues until an entry 
in a level-two VIER is found whose key is greater than or equal 
to the key of the data set. This entry points to a level-one 
VIER that, in turn, contains an entry with a key that is equal 
to the data set key and that points to the format~-l DSCB for the 
desired data set. 


Special Cases in a DSCB Search 


If there 1s only one level in the VTOC index, the entries in the 
VIERs all point to format~-1 DSCBs, so that only one level need 
be searched. 


If an update to the VTOC index requires a new VIER and the 
update is interrupted (for example, because of an I/0 error or a 
system failure), the entry in the level-n VIER may contain a key 
that is greater than the high key in the lower-level VIER 
pointed to by that entry. In this case, two VIERs at level n-l 
may have to be searched. This situation is corrected when DADSM 
next processes the volume. . 
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5. Structure of Linked VIERs 


THE VTOC PACK SPACE MAP (VPSM) 


10 MV 


The VPSM accounts for space on a disk pack. It shows what space 
on the volume has been allocated and what space remains free. 


The map contains bit maps of the cylinders and tracks on the 
volume. A value of one indicates that the cylinder or track has 
been allocated; a value of zero, that it has not been allocated. 
The bit representing a cylinder is set to zero if no tracks on 
the cylinder have been allocated; it is set to one if any track 
has been allocated. Tracks assigned as alternate tracks are 
marked as allocated. 


The VPSM replaces the chain of format-5 DSCBs, but one empty 
format-5 DSCB is left in the VTOC to allow for conversion back 
to a nonindexed VTOC, a process that requires reconstruction of 
a format-5 DSCB chain. 


The format of an index map Cincluding the VPSM) is shown in 
Figure 6 on page ll. 


S/XA System-Data Administration 








ie 








¥ 


Be 

























Large Unit Map 
CVTOC Pack Space Map Only?) 
Small Unit Map 


VTOC Recording Facility Data 
CVTOC Index Map Only) 


Figure 6. An Index Map 


THE VTOC INDEX MAP (VIXM) 


The VIXM contains a bit map where each bit represents one VTOC 
index record CVIR). The status of the bit indicates whether the 
VIR is allocated (1) or unallocated (0). 


An area of the VIXM is reserved for VTOC recording facility 
CVRF) data. (This is the facility that allows detection of and 
recovery from certain errors in an indexed VTOC.) 


A field in the first VIXM record points to the first high-level 
VIER. Another field in the first VIXM record CVIR in Figure 7 
on page 12) contains the number of VTOC index records that 
contain all the space maps. 


THE VTOC MAP OF DSCBS (VMDS) 


The VMDS contains a bit map where each bit represents one DSCB 
in the VTOC. The status of the bit indicates whether the DSCB 
is allocated (1) or unallocated (0). 
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Name Offset Bytes Description 
VIMAP 00CX'00*) 2048 ‘VTOC map , 
VIMH 00CX'00*) GG VTOC map heade . 
VIMID 00CX*00") G Map ID in EBCDIC C'VPSM!, "VIXM', 
| | or 'VMDS') 
VIMRBA 040X'04'") G RBA of this map 
VIMHZPTR O8CX*08') 4 Horizontal RBA pointer to next 
| VIR of this map 
VIMORG 12CX'0C') G Sequence number of the first 
| entry in the map 
VIMVRFDA 16OX'10'") 2 Offset to current VRF data Cif 
VIMVRFSW=1) or offset where VRF 
data may be written (if 
VIMVRFSW=0), Cfirst VIXM only) 
VIMVRFO 18CX'12") 2 Offset to VRF area (first VIXM 
VIR only) 
VIMFLG1 20CX*14*) Flag byte 
VIMVRFSW Les ees VRF data exists if 1 
~XxXxX XXXX Reserved 
VIMLUF1 210X"15") dl Large unit flag byte 
VIMLUOF 22X16") 2 Offset into VIR of large unit map 
(zero if none) 
VIMLUSZ 24CX'18") G Size in bits of large unit map 
VIMSUF1 28CX*1C*) 1 Small unit flag byte 
VIMSUBIT 29CX' 1D") 1 Number of small unit bits per 
large unit (zero if none) 
VIMSUOF 30CX'1E') 2 Offset into VIR of small unit map 
VIMSUSZ 320X'20') q Size in bits of small unit map 
36OX'2G!') 3 Reserved 
VIMVIR 39CX'27') l Number of map records (VIXM only) 
VIMFHLV GOCX*28') G RBA of first high-level VIER 
: C(VIXM only)D 
VIMLUMAP G4CX'2C!) kk Large unit map (kk is VIMLUSZ/8, 
rounded up) a 
VIMSUMAP mm nn Small unit map Cmm is) VIMSUOF, nn a \ 
is VIMSUSZ/8, rounded up) co 
VIMVRF pp aq VRF area (pp is VIMVRFO, qq is _ 


remainder of first VIXM) 


Figure 7. Format of a VTOC Map 


STRUCTURE OF AN INDEXED VTOC 


An indexed VTOC is identical to a nonindexed VTOC, except that, 
for an indexed VTOC, only a single format-5 DSCB exists and is 
empty, and certain format-4 DSCB data (the number of format—0 
DSCBs and the CCHHR of the highest format-1l1 DSCB) is not 
maintained by DADSM. The DOS bit (bit 0 in field DSGVTOCI), set 
to one in the format-4 DSCB, indicates that these fields Cand 
the format-5 DSCB) cannot be relied on. The index bit (bit 7 in 
field DS4VTOCI) is set in the format-4 DSCB; it indicates that a 
VTOC index exists. 


Sen Tr RE Ane nePCente RESTRICTIONS 


A VTOC index data set may not be scratched if the VTOC index is 
active. Neither may a VTOC index data set be renamed if the 
VTOC index is active, unless it is being renamed to another name 
beginning with 'SYS1.VTOCIX.'. A data set may not be renamed to 
a name beginning with 'SYS1.VTOCIX.' if there is already such a 
data set on the volume. Only one data set whose name begins 
with "SYS1.VTOCIX.' may be allocated on a volume. 
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( CREATING THE VTOC AND VTOC INDEX 


To prepare a volume for use Cto initialize it), the Device 
Support Facilities utility is used. One of the things this 
utility does is to build the VTOC. After initialization, this 
VTOC will contain a format-4 DSCB and a format-5 DSCB. For a 
nonindexed VTOC, the format-5 DSCB contains an extent entry for 
all the free space on the volume; the initial number of extents 
in the format-5 DSCB is one or two, depending on where the VTOC 
is located on the volume. If the VTOC is located somewhere 
other than at the beginning or end of the volume, two extent 
entries are needed to describe the free space that precedes and 
follows it. For an indexed VTOC, the format-5 DSCB contains a 
zero. 


A VTOC index can be created when a volume is initialized by 
using the Device Support Facilities command INIT and specifying 
the INDEX Key word. 


A nonindexed VTOC can be converted to an indexed VTOC by using 
the command BUILDIX and specifying the IXVTOC keyword. The 


reverse is also possible by using the BUILDIX command and 
specifying the OSVTOC keyword. 


For more detailed information, see Device Support Facilities 
User's Guide and Reference. | 


PROTECTING THE VTOC AND VTOC INDEX 


| ( Resource Access Control Facility (RACF) 


You can protect the VTOC and VTOC index by using the Resource 
Access Control Facility (RACF). This is done by defining the 
volume serial entity under the RACF class DASDVOL. A user must 
be authorized to the DASDVOL/volume serial entity at the 
following levels: 


e At the UPDATE level, to open the VTOC for output processing 


e At the UPDATE level, to open for output processing any data 
set whose name begins with 'SYS1.VTOCIX.!? | oe 


e At the ALTER level, to allocate, rename, or scratch any data 
set whose name begins with '"SYS].VTOCIX.' 


e At the ALTER level, to rename a data set to any name that 
begins with "SYS1.VTOCIX.'! 


Neither the VTOC nor the VTOC index is protected from being 
opened for input processing by the DASDVOL/volume serial entity. 


Note that neither the VTOC nor the VTOC index can be protected 
through the RACF class DATASET. 
Authorized Program Facility (APF) Requirements 


A program must be authorized by the authorized program facility 
CAPF) to perform any of the following functions: 


6 Opening a VTOC for output processing 


e Opening for output processing a data set whose name begins 
with "SYS1.VTOCIX.'* 





é Allocating, renaming, or scratching any data set whose name 
begins with 'SYS1.VTOCIX.! 
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e Renaming a data set to any name that begins with. 
"SYS1.VTOCIX.! 


~ 


Password Protection 


The VTOC index data set may be password protected. The 
protection is the same as for any password-protected data set. 
Password checking is bypassed if the volume in which the VTOC 
index resides is protected by RACF through the DASDVOL class. 


0 / G/ G 0 


OPERATIONS ON VOLUMES CONTAINING A NONINDEXED VToc 


e Restoring a Volume from a Dump Tape. There are no 
operational requirements if you change the volume serial 
number or do a partial restore that does not modify the 
VTOC. If you do a restore and change the VTOC size without 


changing the volume serial number, the volume must be varied 


offline after it is restored. You should not do a restore 
on a volume with an indexed VTQC. 


e Copying a Volume. There are no operational requirements if 
you change the volume serial number or do not modify the 
VTOC of the receiving volume. If you do a copy and change 


the VTOC size without changing the volume serial number, the 


volume must be varied offline after it is copied. You 
should not do a copy from a volume with an indexed VTOC. 


OPERATIONS ON VOLUMES CONTAINING AN INDEXED VTOC 


You should use Device Support Facilities to convert a VTOC to a 
nonindexed format to update the volume. If you do not, take 
note of the following information: 


e Initializing a Volume. If you do not change the volume 
serial number, the volume should be varied offline before 
starting the job. 


° Restoring a Volume from a Dump Tape. There are no | 
operational requirements if you change the volume serial 


number or do a partial restore that does not modify the VTOC 


or VTOC index. If you do a restore and modify the VTOC or 
VTOC index without changing the volume serial number, the 
volume should be varied offline after it is restored. 


e Copying a Volume. There are no operational requirements if 
you change the volume serial number of the receiving volume 
or do a partial dump without modifying the VTOC or VTOC 
index. If you modify the VTOC or VIOC index without 
changing the volume serial number, the receiving volume 
should be varied offline after it is copied. 


® Shared DASD Considerations. In shared DASD environments, 


whenever the VTOC index is modified or relocated or whenever 


the volume is changed from indexed VTOC to OS VTOC or from 


OS VTOC to indexed VTOC, the device should be varied offline 


‘to the sharing system or systems. 
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ACCESS THE VTOC WITH DADSM MACROS 
( You may use DADSM or CVAF to access the VTOC and its index. CVAF 


access is described in "Accessing the VTOC and its Index with 
CVAF Macros™ on page 25. DADSM macros and associated tasks 


include: 
OBTAIN - Read a DSCB from a VTOC. 
REALLOC - DASD space allocation. 
RENAME - Rename a non-VSAM data set. 
SCRATCH - Release all space and DSCBs for a non-VSAM data set. 


The REALLOC macro is described in "Allocating a DASD Data Set" 
on page 140. 


This section tells how to use the OBTAIN, SCRATCH, and RENAME 
macro instructions. These macros are most commonly used by the 
operating system and the data set utility programs CIEHMOVE, 
IEBCOPY, and IEHPROGM), but you may use them in your own 
routines. The functions you can perform with these macros are: 


e Reading a data set control block from the VTOC—OBTAIN 
e Deleting a data set-—SCRATCH 
e Changing the name of a data set——RENAME 





You can read a data set control block (DSCB) into virtual 
storage by using the OBTAIN and CAMLST macro instructions. 
There are two ways to specify the DSCB that you want to read: 
by using the name of the data set associated with the DSCB, or 
by using the absolute track address of the DSCB. You must 
provide a 140-byte data area in virtual storage, into which the 
DSCB will be read. When you specify the name of the data set, 
an identifier (Cformat-l or format-4) DSCB is read into virtual 
storage. To read a DSCB other than a format-l or a format—-4 


aan DSCB, you must specify an absolute track address (see "Example™ 
( : on page 18). CDSCB po laeres and field descriptions are contained 
in : 


You can delete a non-VSAM data set by using the SCRATCH and 
CAMLST macro’ instructions. This causes the DSCBs for the data 
set to be deleted. 


You can change a data set name by using the RENAME and CAMLST 
macro instructions. This causes the data set name in the 
format-l1 DSCB for the data set to be replaced with the new name. 


Accompanying the descriptions of the macro instructions are 
coding examples, programming notes, and exception return code 
descriptions. 


Note: OBTAIN, SCRATCH, and RENAME macro instructions cannot be 
used with a SYSIN or SYSOUT data set. 


READING A CONTROL BLOCK FROM THE VTOC 


Reading a DSCB by Name (OBTAIN and CAMLST SEARCH) 


If you specify a data set name using OBTAIN and the CAMLST 
SEARCH option, the 96-byte data portion of the identifier 
Cformat-1l1) DSCB and the absolute track address of' the DSCB are 
read into virtual storage. The absolute track address is a 
5-byte field in the form CCHHR. The absolute track address 
field will contain zeros for VSAM and VIO data sets. 


Because the VTOC does not contain a format-1 DSCB for a 
suballocated VSAM data space, an OBTAIN request, which searches 
the VTOC for such a data space's DSCB, fails. If the volume 
contains VSAM data sets, the OBTAIN routine uses information 
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from the VSAM catalog to build a pseudo. PORMA LT 1 DSCB, setting 
its CCHHR to zeros. 


The format is: 





[symbol] OBTAIN 
distname | CAMLST 





“a 
points to the parameter list Clabeled listname) set up by 
the CAMLST macro instruction. 


SEARCH 
this operand must be coded as shown. 


specifies the virtual storage location of a fully qualified 
data set name. The area that contains the name must be 44 
bytes long. 


Note: A DSNAME of 44 bytes of X"'0G* (€X'040404...04") can 
be used to read a format-4 DSCB. 


specifies the virtual storage location of the 6-byte volume 
serial number on which the DSCB is located. 


specifies the virtual storage location of a 140-byte work 
area that you must define. 


Example: In the following example, the identifier (format-1) 

DSCB for data set A.B.C is read into virtual storage using the 
SEARCH option. The serial number of the volume containing the Ny 
DSCB is 770655. - 


OBTAIN | DSCBABC READ DSCB FOR DATA 
% , SET A.B.C INTO DATA 
* AREA NAMED WORKAREA 
DSCBABC CAMLST SEARCH, DSABC, VOLNUM, WORKAREA 
DSABC DC CL44'A.B.C! DATA SET NAME 
VOLNUM DC CL6'770655' VOLUME SERIAL NUMBER 


WORKAREA DS 140C 140-BYTE WORK AREA 


Note: Check the return codes. 


The OBTAIN macro instruction points to the CAMLST macro 
instruction. SEARCH, the first operand of CAMLST, specifies 
that a DSCB be read into virtual storage, using the data set 
name you have supplied at the address indicated in the second 
operand. DSABC, the second operand, specifies the virtual 
storage location of a 44-byte area into which you have placed 
the fully qualified name of the data set whose format-l DSCB is 
to be read. VOLNUM, the third operand, specifies the virtual 
storage location of a 6~byte area into which you have placed the 
serial number of the volume containing the required DSCB 
WORKAREA, the fourth operand, specifies the virtual storage 
aparehenaly of a 140-byte work area into which ue DSCB is to be 
returne 


Control will be returned to your program at the next executable 
instruction following the OBTAIN macro instruction. If the DSCB 
has been successfully read into your work area, register 15 will 
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contain zeros. Otherwise, register 15 will contain one of the 
following return codes. The return codes are shown in decimal, 
with hexadecimal values in parentheses. 


Return Codes from OBTAIN 


Code Meaning 
GOX'04') The required volume was not mounted. 


8CX'08') The format-l DSCB was not found in the VTOC of the 
specified volume. 


12CX'0C*) A permanent I/0 error was encountered, or an invalid 
format-l DSCB was found when processing the 
specified volume, or an unexpected error return code 
was received from CVAF (Common VTOC Access 
Facility). 


L6CX'10°) Invalid work area pointer. 


After execution of these macro instructions, the first 96 bytes 
of the work area contain the data portion of the identifier 
(Cformat-l or format-4) DSCB; the next 5 bytes contain the 
absolute track address CCCHHR) of the DSCB. These 5 bytes will 
contain zeros for VSAM or VIO data sets. 


Reading a DSCB by Actual Device Address (OBTAIN and CAMLST SEEK) 


You can read any DSCB from a VTOC using OBTAIN and the CAMLST 
SEEK option. You specify the SEEK option by coding SEEK as the 
first operand of the CAMLST macro and by providing the absolute 
device address of the DSCB you want to read, unless the DSCB is 
for a VIO data set. Only the SEARCH option can be used to read 
the DSCB of a VIO data set. 


The format is: 


[symbol] OBTAIN 
lListname CAMLST 






»wka rea-rel exp 


points to the parameter list (labeled listname) set up by 
the CAMLST macro instruction. 


SEEK 
this operand must be coded as shown. 


e = 
specifies the virtual storage location of the 5-byte 
absolute device address (CCHHR) of a DSCB. 


—re 


specifies the virtual storage location of the 6-byte volume 
serial number on which the DSCB is located. 


specifies the virtual storage location of a 1940-byte work 
area that you must define. 
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Example: In the following example, the DSCB at actual-device 
address X*'00 00 00 O1 O7' is returned in the virtual storage 
location READAREA, using the SEEK option. The DSCB resides on 
the volume with the volume serial number 108745. 





- OBTAIN ACTADDR READ DSCB FROM 
x LOCATION SHOWN IN CCHHR 
x INTO STORAGE AT LOCATION 
% | NAMED READAREA 
ACTADDR CAMLST SEEK, CCHHR, VOLSER, READAREA 
CCHHR DC XL5'0000000107" ABSOLUTE TRACK ADDRESS 
VOLSER DC CL6'108745' VOLUME SERIAL NUMBER 

| READAREA DS 140C 140-BYTE WORK AREA 


Note: Check the return codes. 


The OBTAIN macro points to the CAMLST macro. SEEK, the first 
operand of CAMLST, specifies that a DSCB be read into virtual 
storage. CCHHR, the second operand, specifies the storage 
location that contains the 5-byte actual-~device address of the 
DSCB. VOLSER, the third operand, specifies the storage location 
that contains the serial number of the volume where the DSCB 
resides. The fourth operand, READAREA, specifies the storage 
location to which the 140-byte DSCB is to be returned. 


Control will be returned to your program at the next executable 
instruction following the OBTAIN macro instruction. If the DSCB 
has been successfully read into your work area, register 15 will 
contain zeros. Otherwise, register 15 will contain one of the 
following return codes. The return codes are shown in decimal, 
with hexadecimal values in parentheses. 


x 
\ 


é 
Ome 


* Bye 


Code Meaning 
GCX'04*) The required volume was not mounted. 


&8CX'08*) The format-1 DSCB was not found in the VTOC of the 
specified volume. 


LT20X'0C') A permanent I/0 error was encountered or an 
| unexpected error return code was received from CVAF. 


16€X?#10*) Invalid work area pointer. 


Z2O0CX'1G") The SEEK option was specified and the absolute track 
aa CCCHHR) is not within the boundaries of the 


| DELETING A DATA SET FROM THE VTOC (SCRATCH AND CAMLST SCRATCH) 


You can use the SCRATCH and CAMLST macro instructions to delete 
a non-VSAM data set. SCRATCH processing deletes the associated 
data set control blocks (DSCBs) and makes the space occupied by 
the data set available for reallocation. Be aware that this 
process does not erase the data from the disk. Data sets that 
contain sensitive data should be erased (overwritten with zeros) 
before their space is made available. 


If you want to scratch a data set being processed using virtual 
input/output (VIO), the data set must have been. allocated for 
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use by your job. Scratching VIO data sets not allocated to your 
job is not allowed. 


If the data set to be deleted is sharing one or more cylinders 
with one or more data sets (a split-cylinder data set), the 
space will not be made available for reallocation until all data 
sets on the shared cylinders are deleted. 


A data set cannot be deleted if the expiration date in the 
identifier (Cformat-1) DSCB has not passed, unless you choose to 
ignore the expiration date. You specify that the expiration 
date is to be ignored by using the OVRD option in the CAMLST 
macro instruction. 


For information on RACF-defined data sets, see 

Information Manual. You may scratch a RACF-defined data set 
Cthat is, the DSCB indicates RACF-defined) only if you have 
alter access authority to either the data set/volume serial in 
the DATASET class, or to the volume serial in the DASDVOL class 
Cif the volume is RACF-defined). 


If a data set to be deleted is stored on more than one volume, 
either a device must be available for mounting the volumes or at 
least one volume must be mounted. In addition, all other 
required volumes must be serially mountable. 


When deleting a data set, you must build a volume list in 
virtual storage. This volume list consists of an entry for each 
volume on which the data set resides. The first two bytes of 
the list indicate the number of entries in the list. Each 
l2-byte entry consists of a 4-byte device code, a 6-byte volume 
serial number, and a 2-byte scratch status code that should be 
initialized to zero. Device codes are presented in Debugging 

ook in the description of UCBTYP. 


If the space to be deleted is a VSAM data space, you must use 
the DELETE command provided by access method services. For 
complete information about the DELETE command, see 

Cc , 


Volumes are processed in the order that they appear in the 
volume list. The volume at the beginning of the list is 
processed first. If a volume is not mounted, a message is 
issued to the operator requesting that a volume be mounted. (CA 
volume mount message will not be issued for a mass storage 
system (MSS) virtual volume; however, a status code will be 
returned to your program.) This is only done if register 0 has 
been loaded with the UCB associated with the device where 
unmounted volumes are to be mounted. (The device must be 
allocated to your job.) If you do not load register 0 with a 
UCB address, its contents must be zero, and at least one of the 
volumes in the volume list must be mounted before the SCRATCH 
macro instruction is issued. 


If the requested volume cannot be mounted, the operator issues a 
reply indicating that the request cannot be fulfilled. <A status 
code is then set in the last byte of the volume pointer Cthe 
second byte of the scratch status code) for the unavailable 
volume, and the next volume indicated in the volume list is 
processed. 


The format is: 


[symbo] 1] SCRATCH J = 
distname | CAMLST SCRATCH 


? 


»? ] 
[,,»OVRD] 





points to the parameter list (labeled listname) set up by 
the CAMLST macro instruction. 
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SCRATCH 
this operand must be coded as shown. 


specifies the virtual storage location of a fully qualified 
data set name. The area that contains the name must be 44 
bytes long. The name must be defined by a C-type define 
eone tems CDC) instruction. | 


specifies the Gsttasi storage location of an area that 
contains a volume list. The area must begin on a halfword 
boundary. 


OVRD | ; 
when coded as shown, specifies that the expiration date in 
the DSCB should be ignored. 


Example: In the following example, data set A.B.C is deleted 
from two volumes. The expiration date in the identifier 
Cformat-1) DSCB is ignored. 


SR 0,0 SET REG 0 TO ZERO 
SCRATCH DELABC DELETE DATA SET A.B.C 
% FROM TWO VOLUMES, 
CX IGNORING EXPIRATION 
* DATE IN THE DSCB 
DELABC CAMLST SCRATCH, DSABC, , VOLIST,,OVRD 
DSABC DC CL44™A.B.C* DATA SET NAME 
VOLIST DC H*2' NUMBER OF VOLUMES 
DC X*3030200E' 3380 DISK DEVICE CODE 
DC CL6'000017' VOLUME SERIAL NO. 
DC H'O' SCRATCH STATUS CODE 
DC X*3030200E' 3380 DISK DEVICE CODE 
DC CL6'000018' VOLUME SERIAL NO. 
DC H*O' SCRATCH STATUS CODE 


Note: Check the return codes and SCRATCH status codes. 


The SCRATCH macro instruction points to the CAMLST macro 
instruction. SCRATCH, the first operand of CAMLST, specifies 
that a data set be deleted. DSABC, the second operand, 
specifies the virtual storage location of a 44-byte area where 
you have placed the fully qualified name of the data set to be 
deleted. VOLIST, the fourth operand, specifies the virtual 
storage location of the volume list you have built. OVRD, the 
sixth operand, specifies that the expiration date in the DSCB of 
the data set to be deleted be ignored. 


When you attempt to delete a password-protected data set that is 
not also RACF-protected, the operating system issues a message 
CIEC301A) to ask the operator at the console or the terminal 
operator of a remote console to enter the password. The data 
set will be scratched only if the password supplied is 
associated with a WRITE protection mode indicator. The 
protection mode indicator is described in Chapter 5, "Password 
Protecting Data Sets.” 


Control is returned to your program at the next executable 
instruction following the SCRATCH macro instruction. If the 
data set has been successfully deleted, register 15 will contain 
zeros, and the scratch status code in the volume list entry for 
each. volume will be set to zero. Otherwise, register 15 will 
contain one of the return codes that follow. To determine 
whether the data set has been successfully deleted from each 
volume on which it resides, you must examine the scratch status 
code, that is, the last byte of each entry in the volume list. 
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Return Codes from SCRATCH 


Code Meaning 


GCX'04') No volumes containing any part of the data set were 
mounted, nor did register 0 contain the address of a 
unit that was available for mounting a volume of the 
data set. The data set may be a VIO data set that 
was not allocated during your job. (This return 
code 1s accompanied by a scratch status code of 5 in 
each entry of the volume list.) 


8CX*08') An unusual condition was encountered on one or more 
volumes. 


120X'0C*) The volume list passed was invalid. The scratch 
status code (the last byte of each volume list 
entry) will not have been modified during scratch 
processing. 


After the SCRATCH macro instruction is executed, the last byte 
of each 1l2-byte entry in the volume list indicates one of the 
following conditions in binary codes: 
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| RENAMING A DATA SET 


Scratch 
Status 
Code 


0 





Meaning 


All DSCBs for the data set have been deleted from 


the VTOC on 


the volume pointed to. 


The VTOC of this volume does not contain the 


format-l 


DSCB for the data set to be deleted. 


The macro instruction failed when the correct 
password was not supplied in the two attempts 


allowed, 


or an attempt was made to scratch a VSAM 


data space or data set cataloged in an ICF catalog. 


The data set was not deleted from this volume 
because either the OVRD option was not specified or 
the retention cycle has not expired. 


A permanent I/0 error was encountered, or an invalid 
format-1l1 DSCB was found when processing this volume, 
or an unexpected error return code was received from 


CVAF. 


It could not be verified that this volume was 
mounted, and no device was available for mounting 


this volume. 


The operator was unable to mount this volume. For 
Mass Storage Systems (MSS), a volume mount failure 


occurred. 


For a JES3-managed virtual volume, JES3 


would not allow the volume to be mounted. 


The specified data set could not be scratched 
because it was being used. 


The DSCB indicates the data set is defined to RACF, 
but either the user is not authorized to access the 
data set or the volume, 


data space, 


catalog, 


| or the data set is a VSAM 
or the data set is cataloged in an ICF 
or the data set is not defined to RACF. 


IN THE VTOC (RENAME AND CAMLST RENAME) 


You rename a data set that is not cataloged in an ICF or VSAM 
catalog by using the RENAME and CAMLST macro instructions. 


These cause the data set name in all format-l DSCBs for the data 
set to be replaced by the new name you supply. 


cannot be renamed. ) 


CVIO data sets 


If a data set to be renamed is stored on more than one volume, 
either a device must be available for mounting the volumes, or 


at least one volume must be mounted. 


In addition, all other 


volumes of the data set must be serially mountable. 


For information on RACF-defined data sets, see 


rename a RACF-defined 


RACF General 
Only a user with alter access authority may 
data set. 


When renaming a data set, you must build a volume list in 


virtual storage. 


This volume list consists of an entry for each 
volume on which the data set resides. 


The first two bytes of 


the list indicate the number of entries in the list. Each 
l2-byte volume list entry consists of a 4-byte device code, a 


6-byte volume serial number, 


that should be initialized to zero. 


an 
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and a 2-byte rename status code 


Device codes are presented 


Volumes are processed in the order that 





























they appear in the volume list. The first volume on the list is 
processed first. If a volume is not mounted, a message is 
issued to the operator requesting that the volume be mounted. 

CA volume mount message will not be issued for an MSS volume; 
however, a status code will be returned to your program.) This 
is only done if you indicate the direct access device on which 
unmounted volumes are to be mounted by loading register 0 with 
the address of the UCB associated with the device to be used. 
(The device must be allocated to your job.) If you do not load 
register 0 with a UCB address, its contents must be zero, and at 
least one of the volumes in the volume list must be mounted. 
before the RENAME macro instruction is executed. 


lf the operator cannot mount a volume in the volume list, a 
reply is issued that the request cannot be fulfilled. A status 
code is then set in the last byte of the volume list entry (the 
second byte of the rename status code) for the unavailable 
volume, and the next volume indicated in the volume list is 
processed or requested. 


The format is: 


RENAME 
CAMLST 





points to the parameter list (labeled listname) set up by 
the CAMLST macro instruction. 


RENAME 
this operand must be coded as shown. 


specifies the virtual storage location of a fully qualified 
data set name to be replaced. The area that contains the 
name must be 44 bytes long. The name must be defined by a 
C-type define constant (DC) instruction. 


specifies the virtual storage location of a fully qualified 
data set name that is to be used as the new name. The area 
that contains the name must be 44 bytes long. The name 
must be defined by a C-type Define Constant (CDC) 
instruction. 


specifies the virtual storage location of an area that 
contains a volume list. The area must begin on a halfword 
boundary. 
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Example: In the following example, data set A.B.C is renamed 
D.E.F. The data set resides on two volumes. | | 





SR 0,0 SET REG 0 TO ZERO 
RENAME DSABC CHANGE DATA SET 
| NAME A.B.C TO D.E.F 


DSABC CAMLST RENAME, OLDNAME,NEWNAME, VOLIST 


OLDNAME DC CL44°A.B.C! OLD DATA SET NAME 
NEWNAME DC ~ CL44°D.E.F* NEW DATA SET NAME 
VOLIST DC H*2' TWO VOLUMES 

DC X*3030200E' 3380 DISK DEVICE CODE 

DC CL6'000017! VOLUME SERIAL NO. 

DC H‘O! RENAME STATUS CODE 

DC X*3030200E' 3380 DISK DEVICE CODE 

DC CL6'000018' VOLUME SERIAL NO. 

DC H'o' RENAME STATUS CODE 


Note: Check the return codes and RENAME status codes. 


The RENAME macro instruction points to the CAMLST macro 
instruction. RENAME, the first operand of CAMLST, specifies 
that a data set be renamed. OLDNAME, the second operand, 
specifies the virtual storage location of a 44-byte area where 
you have placed the fully qualified name of the data set to be 
renamed. NEWNAME, the third operand, specifies the virtual 
storage location of a 44~byte area where you have placed the new 
name of the data set. VOLIST, the fourth operand, specifies the 
virtual storage location of the volume list you have built. 


Control is returned to your program at the next executable | 
instruction following the RENAME macro instruction. If the data 
set has been successfully renamed, register 15 will contain 
zeros, and the rename status code in the volume list entry for 
each volume will be set to zero. Otherwise, register 15 will 
contain one of the return codes below. To determine whether the 
data set has been successfully renamed on each volume where it 
resides, you must examine the rename status code, the last byte 
of each entry in the volume list. | 


A 


Return Codes from RENAME 


Code Meaning 


GCX'04') No volumes containing any part of the data set were 
mounted, nor did register 0 contain the address of a 
unit that was available for mounting a volume of the 
data set to be renamed. The data set may be a VIO 
data set and cannot be renamed. (This return code 
is accompanied by a rename status code of 5 in each 
entry of the volume list.) | 


8OCX'08*) An unusual condition was encountered on one or more 
volumes. 


12€X*0C*) The volume list passed was invalid. The rename 
status code, the last byte of each volume list 
entry, will not have been modified during rename 
processing. 
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After the RENAME macro instruction is executed, the last byte of 
each 12-byte entry in the volume list indicates one of the 
following conditions in binary code: 


Rename 

Status 

Code Meaning | 

0. The format-1 DSCB for the data set has been renamed 
in the VTOC on the volume pointed to. 

l The VTOC of this volume does not contain the 
format-1l DSCB for the data set to be renamed. 

2 The macro instruction failed when the correct 
password was not supplied in the two attempts 
allowed, or the user tried to rename a VSAM data 
space or VSAM data set cataloged in an ICF catalog. 

3 A data set with the new name already exists on this 
volume. 

G A permanent I/O error was encountered, or an invalid 
format-l DSCB was found when trying to rename the 
data set on this volume, or an unexpected error 
return code was received from CVAF. 

5 It could not be verified that the volume was 

mounted, and no device was available for mounting 
the volume. 

6 The operator was unable to mount this volume. For 
Mass Storage Systems (MSS), a volume mount failure 
occurred. For a JES3-managed virtual volume, JES3 
would not allow the volume to be mounted. 

7 The specified data set could not be renamed on this 
volume because it was being used. 

8 The data set is defined to RACF but either the user 


1s not authorized to alter the data set or the data 
set is defined to RACF on multiple volumes. 


When you attempt to rename a password-protected data set, the 
operating system issues a message (IEC301A) to ask the operator 
or remote console operator to verify the password. The data set 
will be renamed only if the password supplied is associated with 
a WRITE protection mode indicator. The protection mode 
indicator is described in Chapter 4, "Password Protecting Data 
Sets™ on page 84. 





You may use CVAF or DADSM to access the VTOC or its index. 
DADSM cee 1s described in "Access the VTOC with DADSM Macros™ 
on page 


CVAF macros and associated tasks include: 


CVAFDIR—Directly access DSCBs or VTOC index records. 
CVAFDSM—Obtain volume free space information. 
CVAFSEQ—Retrieval of the following: 

- Data set names from an active VTOC index. 

- DSCBs in physical~-sSequential order. 

- DSCBs in data set name order Cindex required). 
CVAFTST~—Determine if a DASD volume has an active VTOC index. 


Chapter 1. Managing the Volume Table of Contents (CVTOC) 25 








Appendix A, "CVAF - VTOC Access Macros™ on page 178 contains 
detailed descriptions of these macros. Appendix B, "Examples of 
VTOC Access Macros™ on page 196 contains examples of their use. 


Serialization and Updating 


CVAF requires that you provide all necessary system resource 
serialization for your request. You can ensure the integrity of 
multiple data elements (sets of DSCBs and/or VIRs) returned by 
CVAF only when you provide adequate resource serialization. This 
exposure is compounded if multiple requests are required for the 
compilation of a desired set of DSCBs and/or VIRS. You must 
weigh possible system performance loss due to serialization 
against the potential loss of data integrity. 


Updates made without adequate serialization may compromise the 
integrity of the volume's VTOC, the VTOC index, and/or any 
associated data set. 


CVAF honors requests to modify the volume's VTOC and/or index 
for authorized programs only. CVAF assumes that an authorized 
program holds an exclusive RESERVE Cor ENQ) on the qname (major 
name) of SYSVTOC, rname (minor name) of the volume's serial 
number, with the scope of SYSTEMS. 


The SYSVTOC qname does not serialize access to the format-1 DSCB 
for a data set. You may provide this serialization by 
allocating the data set with disposition OLD, MOD, or NEW Cnot 
SHR). This causes the proper ENQ, ensuring that no other job 
can update that data set's format-l DSCB. 


Identifying the Volume 


Using Registers 


If you are authorized, you may identify the volume to the 
CVAFDIR, CVAFDSM, and CVAFSEQ macros by specifying the address 
of its UCB. If you are not authorized, you must identify the 
volume by specifying the address of a SAM or EXCP DEB opened to 
the volume's VTO 


The DEB can be obtained by opening a DCB using the RDJFCB and 
OPEN TYPE=J macros. The DCBs DDNAME is that of a DD statement 
allocated to the unit whose VTOC is to be accessed. After 


' assuing the RDJFCB macro, the JFCBDSNM field is overlaid with 


the data set name of the format-4 DSCB: 44X'0G'. The DCB is 
opened for INPUT using OPEN TYPE=J. The DEB address is in DCB 
field, DCBDEBA. The OPEN macro is described under the section 
"QOPEN—-Initialize Data Control Block for Processing the JFCB™ on 
page 122; the RDJFCB macro is described under "RDJFCB—Read a 
Job File Control Block™ on page 118. 


If a CVAF macro call has specified IOAREA=KEEP, a subsequent 
CVAF call using a different CVPL may omit the UCB and DEB 
Keywords and supply the IQAREA address from the other CVPL. You 
can use the IOAREA Keyword to do this. 


The above does not apply to the CVAFTST macro. Only a UCB may 
be euler os to identify the VTOC, and no authorization is 
required. 


Register 1 contains the address of the CVAF parameter list 
(CVPL). Register 15 contains the return code when processing 
for a function is complete. 
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Generating a CVPL (CVAF Parameter List) 


— The CVAFTST macro expands to provide its only parameter (CUCB 

7 address) in register 1, and calls the associated CVAF module. 
All of the remaining CVAF macros use the CVPL to pass parameters 
to CVAF. CVAF uses the CVPL to return information related to the 
CVAF request. 


CVAF generates a CVPL when you specify the CVAFDIR, CVAFDSM, or 
CVAFSEQ macro with MF=L or MF=I as a subparameter. If you do 
not specify the MF subparameter, MF=I is the default. .The 
CV1IVT bit indicates whether an indexed or nonindexed VTOC is 
being accessed. The CVSTAT field contains feedback when an 
error occurs. The address of the map records buffer list is 
returned in the CVMRCDS field. The address of the VIER buffer 
list is returned in the CVIRCDS field. The CVAF I/O area 
address is returned in the CVIOAR field. 


You may use the CVPL generated by the MF=L or MF=I form of the 
CVAFDIR, CVAFDSM, or CVAFSEQ macro (by using the MF=E keyword) 
to execute a different function from the one specified by the 
macro that originally generated the CVPL. 


The ICVAFPL macro maps the CVPL. The format of the CVPL is 
shown in Figure 8. 


Name Offset Bytes Description 
CVPL 
CVLBL 0OCX'00') G EBCDIC ™"CVPL"™ 
CVLTH 040X'04') 2 
CVFCTN 06CX*06') l Function Byte (See Figure 9 on 
page 28) 

CVSTAT 070X'07'°) 1 Status Information 

Fk CVFLI1 O08CX'08") 1 First Flag Byte 

( : CV1IVT ar Indexed VTOC Accessed 

cw CV1LIOAR me eee IOAREA=KEEP 
CV1PGM ee BRANCH=CYES, PGM) 
CVIMRCDS wae MAPRCDS=YES 
CV1LIRCDS ies ee IXRCDS=KEEP 
CVIMAPIX : MAP=INDEX 
CVIMAPVT ss MAP=VTOC 
CVIMAPVL eg MAP=VOLUME 
CVFL2 09CX'09') 1 Second Flag Byte 
CV2HIVIE des 8 HIVIER=YES 
CV2VRF a areas YRF data exists 
CV2CNT orks ee COUNT=YES 
CV2RCVR oe | RECOVER=YES 
CV2SRCH ree SEARCH=YES 
CV2DSNLY Lane DSNONLY=YES 
CV2VER ae VERIFY=YES 
CV2NLEVL ae New highest level VIER Coutput) 
CVUCB 12€X*0C') 4G UCB address 
CVDSN L6CX'10') G Data set name address 
CVBUFL 200€X*#14G°) G Buffer list address 
CVIRCDS 240X'18') G Index VIRs buffer list address 
CVMRCDS 28COX*1C") G Map VIRs buffer list address 
CVIOAR 320X*20') G I/O area address 
CVDEB 360X'24') G DEB address 
CVARG GOCX'28!') q Argument address 
CVSPACE GGCX'*2C') G SPACE parameter list address 
CVEXTS 48(X'30') G Extent table address 
CVBUFL2 520X'3G") % New VRF VIXM buffer list address 
CVVRFDA 560X'38") G VRF data address 
CVCTAR 60CX*3C") G Count area address 
Figure 8. Format of the CVAF Parameter List (CCVPL) 
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The possible contents of the CVFCTN field in the CVPL end their 
meanings are as follows: 





Name Description 

CVDIRD X*01'*-CVAFDIR ACCESS=READ | 
CVDIWR X*02'-CVAFDIR ACCESS=WRITE | 
CVDIRLS X*03'-CVAFDIR ACCESS=RLSE 
CVSEQGT X'04'-CVAFSEQ ACCESS=GT 
CVSEQGTE X*05*-CVAFSEQ ACCESS=GTEQ 
CVDMIXA X*06'-CVAFDSM ACCESS=IXADD 
CVDMIXD X*'07°-CVAFDSM ACCESS=IXDLT 
CVDMALC X*'08°-CVAFDSM ACCESS=ALLOC 
CVDMRLS X*09*-CVAFDSM ACCESS=RLSE 
CVDMMAP X*OA'-CVAFDSM ACCESS=MAPDATA 
CVVOL X*OB*-CVAFVOL ACCESS=VIBBLD 
CVVRFRD X*'0C*-CVAFVRF ACCESS=READ 
CVVRFWR X'OD*-CVAFVRFE ACCESS=WRITE 


Figure 9. CVFCTN Field of CVPL - Contents and Definitions 


Buffer Lists 


A buffer list consists of one or more chained control blocks, 
each with a header and buffer list entries. The header 
indicates whether the buffer list is for DSCBs or VTOC index 
records. The entries point to and describe the buffers. 


Buffer lists can be created in two ways: 


e Directly, when you fill in the arguments and buffer 
addresses of DSCBs or VIRs to be read or written 


e Indirectly (by CVAF), when you code the IXRCDS=KEEP and/or 
MAPRCDS=YES keywords 


CVAF buffer lists are mapped by the ICVAFBFL macro. Figure 10 
on page 29 shows the format of a buffer list header. Figure ll 
on page 30 shows the format of a buffer list entry. 


BUFFER LIST HEADER: The buffer list header indicates whether 
the buffer list describes buffers for DSCBs or for VTOC index 
records. The DSCB bit must be set to one and the VIR bit to 
zero in order for CVAF to process a request to read or write a 
DSCB. CVAF requires that you provide buffer lists and buffers 
in the caller's protect key. CVAF uses the protect key and 
subpool fields in the buffer list header only if you code 
ACCESS=RLSE. 


\ 


es 


Each buffer list header contains a count of the number of 
entries in the buffer list that directly follows the header. 


The forward chain address is used to chain buffer lists 
together. DSCB buffer lists must not be chained to VIR buffer 
pice and VIR buffer lists must not be chained to DSCB buffer 
ists. 





28 MVS/XA System-Data Administration. 








Name 
BFLHDR 
BFLHNOE 
BFLHFL 
BFLHKEY 


BFLHVIR 
BFLHDSCB 


BFLHSP 
BFLHFCHN 


Figure 10. 








The format of the buffer list header is shown in Figure 10. 





Offset Description 
OCX*'O00*) Buffer list header 
OCX*'00') 1 Number of entries 
1¢X'01!') 1 Flag byte and key 
XXKXK see Protect key of buffer list and 
buffers 
; eee Buffer list entries describe VIRs 
me ara Buffer list entries describe 
DSCBs 
cigiteie. 7 30C Reserved 
2OX'02') 1 Reserved 
3CX'03') 1 Identifies the subpool of buffer 
list and buffers 
GCOX'04') q Forward chain address of next 


buffer list 


Format of a Buffer List Header 


BUFFER LIST ENTRY: A buffer list contains one or more entries. 
Each entry provides the buffer address, the length of the DSCB 
or VIR buffer, the argument, and an indication whether the 
argument is an RBA, a TTR, or a CCHHR. 


The fields and bit uses are listed below. 


® For a VIR buffer, the TTR and CCHHR bits must be 0, and the 
RBA bit must be l. 


Y For a DSCB buffer, the RBA bit must be 0, and one of either 
aren or CCHHR bits must be set to 1 Cthey must not both 
e : 


e The BFLEAUPD bit is an output indicator from CVAF that the 
BFLEARG field of a VIR buffer list was updated. 


e The BFLEMOD bit indicates that a VIR buffer was modified and 
must be written; if no BFLEMOD bits are on in any of the 
entries for a CVAFDIR ACCESS=WRITE, all buffers are written. 


® The BFLESKIP bit is used to cause an entry to be ignored. 


e The BFLEIOER bit is an output indicator from CVAF to 
indicate an I/0 error occurred during reading or writing of 
the DSCB or VIR. 


e The BFLELTH field is the length of the buffer; for a DSCB 
buffer, the length must be 96 or 140; for a VIR buffer, the 
length must be the length of the buffer divided by 256. 


e The BFLEARG field is the argument of the DSCB or VIR. 
Specify the desired format of the 5-byte field by setting 
either the BFLECHR, BFLETTR, or BFLERBA bit to 1. The 
respective BFLEARG values and formats are as follows: 

_ CCHHR=5 byte CCHHR 
- TTR=OTTRO . 
= RBA=One byte of 0 followed by a 4-byte RBA 
The optional and required values for BFLEARG are dependent upon 


the variables associated with a given request. These are 
described in the following topics. 
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The format of the buffer list entry is shown in Figure ll. 





Name Offset Bytes Description 
BFLE OCX*00*) 12 Buffer list entry. 
BFLEFL OCX'00") 1 Flag byte | | 
BFLERBA dee Argument is RBA 
BFLECHR oles.« Argument is CCHHR 
BFLETTR sat hes Argument is TTR 
BFLEAUPD eared. Saat CVAF updated argument field 
BFLEMOD ae eee Data in buffer has been modified 
BFLESKIP ie eae, Beka Skip this entry 
BFLEIOER areas ead ks I/O error 
ei te ok Reserved 
CX Ol) ] Reserved 
BFLELTH 20X02") l Length of VIR buffer divided by 
a 256 or length of DSCB buffer 
BFLEARG 30X'03') 5 Argument of VIR or DSCB 
BFLEATTR GCX'04') 3 TTR of DSCB 
BFLEARBA GCX'04') Gq RBA of VIR 
BFLEBUF 8CX'08') 4 Buffer address 
Figure 11. Format of a Buffer List Entry 


| Accessing the DSCB Directly 


CVAFDIR may be used to read or write a DSCB. CVAFDIR may also 
be used to read or write VTOC index records for indexed VTOCs. 
"CVAFDIR Macro™ on page 178 discusses detailed information about 
the CVAFDIR VTOC access macro. 


After a CVAFDIR call, the CVAF parameter list bit, CVLIVT, may 
be tested to determine whether the VTOC is indexed or 
nonindexed. 


SPECIFYING A DATA SET NAME TO READ OR WRITE A DSCB: If you want 
to read or write a single DSCB by specifying only the data set 
name (that is, BFLEARG is zero), you must specify either 
ACCESS=READ or ACCESS=WRITE. 


Specify the address of the data set name in the DSN Keyword, 
then specify the address of the buffer list in the BUFLIST 
keyword. Each of these areas and the associated buffers must be 
in your protect key. 


The buffer list must contain at least one buffer list entry with 
the skip bit off and a pointer to a 96-byte buffer. You must 
not provide 140-byte buffers. You may chain buffer lists 
together, but CVAF uses only the first eligible entry. 


For an indexed VTOC, the index will be searched for the data set 
name and, if it is found, the DSCB argument obtained will be put 
in the buffer list entry and used to read or write the DSCB. If 
the data set name is not found in the index, a key search of the | 
VTOC will. be performed. 


For a nonindexed VTOC, a channel program will be used to do a 
key search of the VTOC to locate the data set name and read or 
write the DSCBs. If the data set name is found, the DSCB 
argument will be put in the buffer list entry. 


The DSCB argument returned in the buffer list entry will be in 
the format determined by the buffer list entry bits BFLECHR or 
BFLETTR. | 
If the data set name is not found in the VTOC, register 15 will 
lia ; return code of 4, and CVSTAT will contain an error 
code o 
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SPECIFYING THE DSCB LOCATION: If you want to read or write a 
DSCB by specifying the DSCB's location (that is, BFLEARG), you 
must specify either ACCESS=READ or ACCESS=WRITE. 


Specify the address of the data set name in the DSN Keyword, 
then specify the address of the buffer list in the BUFLIST 
keyword. Each of these areas and the associated buffer(s) must 
be in your program's protect key. 


The buffer list must have at least one buffer list entry with 
the skip bit off and a pointer to a 96-byte or 190-byte buffer. 
You may chain buffer lists together, but CVAF uses only the 
first eligible entry. 


If the buffer is for a 96-byte read or write, CVAF issues a 
channel program to verify that the Key in the DSCB is the same 
as the 44-byte data set name you provide. CVAF does not execute 
the read or write unless they match. If they do not match, CVAF 
ignores the specified BFLEARG and reads or writes the DSCB 
according to the rules given in "Specifying a Data Set Name to 
Read or Write a DSCB" on page 30. 


If the buffer is for a 140-byte read or write, CVAF issues a. 
channel program to read or write the DSCB at the location 
specified in the buffer list entry. CVAF does not use the data 
set name you specified. If you specify VERIFY=YES, CVAF 
verifies that the designated DSCB is a format— 0 DSCB before 
issuing the write channel program. 


READING OR WRITING VTOC INDEX RECORDS: VIRs may be read or 
written explicitly using the BUFLIST keyword or may be read 
implicitly using the IXRCDS and MAPRCDS keywords. A buffer list 
address may be supplied in the BUFLIST keyword to read or write 
one or more VIRs. The buffer list header must have the VIR bit 
set to one and the DSCB bit set to zero. Each entry in the 
buffer list Cand subsequent buffer lists if more than one is 
chained) is inspected. If the skip bit is set to zero, the RBA 
bit is set to one Cand the CCHHR and TTR bits are set to zero), 
and the buffer address is nonzero, the entry will be processed. 
The RBA in the argument field of the buffer list entry is used 
to read or write a VIR using the buffer address. Read and write 
requests will be in the order of entries in the buffer list. 


Each of the storage areas you provide must be in your program's 
protect Key. 


For a write request, the modification bit in the buffer list 
entries 1S inspected. If the bit is not set in any entry, all 
are written. The modification bit is set to zero for entries 
whose VIR is written. 


Map records and the first high-level VTOC index entry record may 


be read by supplying the keywords MAPRCDS=YES and/or IXRCDS=KEEP 
and, at the same time, not supplying an address in the oon, 
parameter list CVMRCDS/CVIRCDS fields. 


READING MAP RECORDS AND VIERS: To read and retain in virtual 
storage the VTOC index map records and first high-level VIER, 
either ACCESS=READ or ACCESS=WRITE must be coded. Neither the 
DSN field nor the BUFLIST field is required. 


MAPRCDS=YES must be coded to read and retain map records. The 
CVAF parameter list field CVMRCDS must be zero. CVAF will 
obtain a buffer list with the number of entries and buffers 
required to read all the map VIRs. The buffer list address will 
be put in the CVMRCDS field by CVAF. : 


IXRCDS=KEEP is coded in order to read and retain the first 
high-level VIER and (Cif an index search is required) all VIERs 
read. If the CVAF parameter list field CVIRCDS is zero, CVAF 
will obtain a buffer list with entries and buffers and read the 
first high-level VIER. The number of entries and number of 
buffers are determined by CVAF. If CVIRCDS is not zero, only 
VIERs required for an index search will be read. 
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The integrity of the maps and VIER read can only be ensured if 
you are enqueued on the VTOC and, in the case of shared DASD, 
reserved to the unit. 


Map and VIER buffers obtained by CVAF Cand retained) must be 
released by a subsequent CVAF call. 


RELEASING BUFFERS AND BUFFER LISTS OBTAINED BY CVAF: There are 
three ways to release buffers and buffer lists obtained by CVAF. 


® Code MAPRCDS=NO or MAPRCDS=(NO,addr) for any specification 
of ACCESS in order to free the MAP records buffer list. 


e Code IXRCDS=NOKEEP or IXRCDS= C(NOKEEP, addr) for any 
specification of ACCESS in order to free the index records 
buffer list. 


® Code ACCESS=RLSE and supply a buffer list address through 
the BUFLIST keyword for a subsequent CVAF call. 


CVAF will free all eligible buffers and any buffer lists if they 
become empty. Eligible buffers are those pointed to by buffer 
list entries with the skip bit off. A buffer list will be freed 
if no buffer list entry has the skip bit on. If buffer lists 
are chained together, all buffer lists will be checked and freed 
if appropriate. 





You must ensure that you do not request CVAF. to release the same 
areas list twice by supplying its address in more than one 
place. 


| Accessing DSNs or DSCEs in Sequential Order 


Each CVAFSEQ call may request the return of one of the 


following: “a 
e eile format-l or format-4 DSCB in indexed (data-set-name) \ 
order 


@ One or more DSCBs in physical-~sequential order Cbut only one 
DSCB can be requested by an unauthorized caller) 


e The next data set name in the index 


| CVAF reads the DSCBs into buffers supplied through the BUFLIST 
keyword. "CVAFSEQ Macro™ on page 190 discusses detailed 
information about the CVAFSEQ VTOC access macro. 


The argument of each DSCB read is also supplied in the buffer 
list. DSCBs of 96 bytes must be requested in the buffer list 
for indexed access; 1490 bytes is required for 
physical-sequential access. 


If indexed order is chosen, the VTOC index is used to return 
each format-l or format-4 DSCB whose name is in the index. An 
option CDSNONLY=YES) allows only the data set names in the VTOC 
index, but not the DSCBs, to be obtained. In this case, the 
CCHHR of the DSCB is returned in the argument area supplied 
through the ARG keyword. The DSN area supplied is updated at 
nade CVAFSEQ call to contain the data set name of each DSCB 

rea 


INITIATING INDEXED ACCESS (DSN ORDER): To initiate indexed 
access (DSN order), either supply in the area coded through the 
DSN keyword 44 bytes of binary zeros (to indicate the first data 
set name in the index) or supply the data set name you want to 
serve as the starting place for the index search. 


The name returned in the DSN area will be the one equal to or 
greater than the DSN supplied, depending on the specification of 
the ACCESS keyword. The DSN field is updated by CVAF. 
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The ACCESS keyword determines whether the search is for a DSN 
greater than or equal to that supplied. 


If DSNONLY=NO is coded, the DSCB and argument are returned to 
you, using the buffer list provided through the BUFLIST keyword. 
The first entry in the buffer list with a skip bit of zero anda 
nonzero buffer address is used. The argument value is supplied 
if either the TTR or CCHHR bit is set in the buffer list entry. 
The default is CCHHR. The DSCB size in the buffer list entry 
must be 96 bytes for indexed access. 


If DSNONLY=YES is coded, the CCHHR argument is supplied in the 
ARG area. 


Note that the data set name of the format-4 DSCB is in the index 
and that its name (4964 bytes of X'04') may be returned to you. 
The format-4 DSCB's name is likely to be the first data set name 
in the VTOC index. 


INITIATING PHYSICAL~SEQUENTIAL ACCESS: To initiate 
physical-sequential access, the DSN keyword must be omitted or 
DSN=0 must be coded. The argument field in the first buffer 
last entry must be initialized to zero or to the argument of the 
DSCB to begin the read. If the argument is zero, the argument 
used will be the start of the VTOC. | 


The DSCB size must be set to 140 in buffer list entries. 


The specification of ACCESS will determine whether the DSCB 
pees argument is supplied or the DSCB following it is to be 
read. 


For example, to read the first DSCB (the format-4 DSCB) in the 
VTOC, the BFLEARG in the first buffer list entry may be set to 
zero, and ACCESS=GTEQ coded in the CVAFSEQ macro. If ACCESS=GT 
1s See Ney coded, the second DSCB (the first format-5 DSCB) 
is read. 


If you are authorized, as many DSCBs as there are entries in the 
buffer list will be read with a single CVAF call. Only one DSCB 
will be read if you aren'ft authorized. 


Only one buffer list is used; a second buffer list chained to 
the first will not be inspected. All entries in the buffer list 
will be used for authorized callers. The skip bit will not be 
inspected. Each entry must have a buffer address, the length 
field set to 140, and the TTR or CCHHR bit set Cif neither bit 
is set, the CCHHR bit will be set on). Only the first entry 
will be used for unauthorized callers. The argument field of 
each buffer list entry will be updated by CVAF with the argument 
of the DSCB. The argument value is returned in either TTR or 
CCHHR format, depending on whether the TTR or CCHHR bit is set 
in the buffer list entry. The default is CCHHR. 


Only the argument in the first entry is used to begin the 
search. Arguments in subsequent entries are not inspected. If a 
nonzero argument value is supplied in the first entry, there 
must be a DSCB with that argument. 


End-of-data is indicated with a return code of 4 in register 15 
and CVSTAT set to X'20'. Each buffer list entry following the 
last DSCB read has its argument field set to zero (this may be 
the first entry if no DSCBs are read). 


Note that all DSCBs, including format-0 DSCBs, are read. You 
cannot be certain that you have read all format-1 through -6 
DSCBs until the entire VTOC has been read. For a nonindexed 
VTOC, the CCHHR of the last format-1l DSCB is contained in the 
format-4 DSCB field DSGHPCHR; format-2 through -6 DSCBs may 
reside beyond that location. For an indexed VTOC, the VMDS 
contains information about which DSCBs are format-0 DSCBs. 
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| Obtaining Information from the VTOC Index 


ACCESS=MAPDATA is used to obtain information contained in the 
space maps. "CVAFDSM Macro™ on page 185 discusses detailed 
information about the CVAFDSM VTOC access macro. 





To count the number of unallocated VIRs in the VTOC index space 
map CVIXM), COUNT=YES and MAP=INDEX are coded. The number of 
unallocated VIRs is returned in the 4-byte area supplied through 
the CTAREA keyword. 


To count the number of format-0 DSCBs, COUNT=YES and MAP=VTOC 
are coded. The number of format-0 DSCBs in the VTOC map of 
DSCBs VMDS is returned in the 4-byte area supplied through the 
CTAREA keyword. 


To obtain one or more free space extents from the VTOC pack 
Space map CVPSM), COUNT=NO and MAP=VOLUME are coded. The 
extents are returned in the area supplied through the EXTENTS 
keyword. Each extent is returned in a 5~byte XXYYZ format, the 
same as for a format-5 DSCB extent, where XX is the relative 
track address (RTA) of the first track of the extent, YY is the 
number of whole cylinders in the extent, and Z is the number of 
additional tracks in the extent. The RTA supplied to CVAF in 
the first Cor only) extent will serve as a starting point for 
the VPSM search; the extent returned will be the next free 
extent with a higher starting RTA than the one supplied. 


If all the unallocated extents in the VPSM are supplied before 
filling in all the extents supplied, the remaining extents are 
set to zero. Register 15 is set to 4 on return, with the CVSTAT 
field in the CVPL set to X'20' to indicate the end of data. 


| DIAGNOSING VTOC ERRORS 


a 
WY 


Actions Taken When an Error Occurs 
These actions are taken if an error occurs: 


e If an index structure error is detected, DADSM or CVAF will 
cause the VTOC index to be disabled. The indexed VTOC bit 
will be zeroed in the format-4 DSCB. A software error 
record will be written to SYSI].LOGREC. A system dump is 
taken. The VTOC will be converted to a nonindexed format at 
the next DADSM allocate or extend call. 


e If a program check, machine check, or other error occurs 
while using a VTOC access macro, a SYS1.LOGREC message is 
written, and a system dump is taken. 


e An error code is put in the CVSTAT field of the CVPL. The 
values and explanations of these error codes are listed in 
ial amegr "VTOC Index Error Message and Associated Codes” 
on page . : 


Recovering from System or User Errors 


Neither the VTOC nor the VTOC index need be recovered from a 
user error caused by an unauthorized user, because an 
unauthorized user cannot modify a VITOC 


A system error will affect a VTOC and VTOC index, probably by 
interrupting DADSM while it is updating, thus leaving the VTOC 
and/or the VTOC index ina partially updated state. Both the 
VTOC and the VTOC index are designed to cause DADSM to recover 
from such an interruption. 


For a nonindexed VTOC Cor a VTOC with an index that has been 
disabled), a subsequent call to DADSM ALLOCATE or EXTEND will 
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cause VTOC convert routines to reestablish the free space 
( Cformat-5 DSCBs). 


For an indexed VTOC, a subsequent call to any DADSM function 
will cause the recovery of the previous interrupt Ceither by 
backing out or completing the interrupted function). 


GTF Trace 


A trace function exists to trace all CVAF calls for VTOC index. 
output I/0, all VTOC output I/0, and all VTOC index and space 
map modifications. For information on this function, see CVAF 


LISTING A VTOC AND VTOC INDEX 


A VTOC and VTOC index can be listed using the IEHLIST utility 
program. Dump, formatted, or abridged listings can be obtained 
by using the LISTVTOC command of IEHLIST. 
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The execute-channel-program CEXCP) macro instruction provides 
you with complete control of the data organization based on 
device characteristics. This chapter contains a general 
description of the function and application of the EXCP macro 
instruction, accompanied by descriptions of specific control 
blocks and macro instructions used with EXCP. Factors that 
affect the operation of EXCP, such as device variations and 
program modification, are also discussed. 


Before reading this chapter, you should be familiar with system 

functions and with the structure of control blocks, as well as 

with the operational characteristics of the I/“0 devices required 

by your channel programs. Operational characteristics of 

ae ee I70 devices are described in IBM publications for each 
evice 





You also need to understand the information in these 
publications: 


e Data Administration Guide contains the standard procedures 
for I/0 processing under the operating system. 





contaane the entormation necessary to oda urcurshe 6 the 
assembler language. 


1 : : describes 
the system macro PRetructions that an oye need in programs 
coded in the assembler language. 





me 


¢ Debugging Handbook, Volumes 2 through 5, contain format and . 3 
field descriptions of the system control blocks referred to ee 


in this chapter. 


® Conversion Notebook describes the factors to consider when 
A et A from MVS/370 at the MVS/SP Version 1 level to 
AXA. | 


The execute-channel-program CEXCP) macro instruction causes a 
supervisor-call interruption to pass control to the EXCP 
processor. (I/O process is the name we will use for the EXCP 
processor and the I/O supervisor. For our purposes, it's 
unnecessary to understand how input/output processing is divided 
between the two.) EXCP also provides the I/O supervisor with 
control information regarding a channel program to be executed. 
When an IBM access method is being used, an access method 
routine is responsible for issuing EXCP. If you are not using 
an IBM access method, you must issue EXCP in your program. (The 
ries tre aaa iach cannot be used to process SYSIN or SYSOUT 
ata sets. 


You issue EXCP primarily for I/0 programming situations to which 
the standard access methods do not apply. If you are writing 
your own access method, you must include EXCP for I/0 
operations. EXCP must be used for processing nonstandard 
labels, including reading and writing labels and positioning 
magnetic tape volumes. 


To issue EXCP, you must provide a channel program (a list of 
channel command words) and several control blocks in your 
program area. The I/O process then schedules I/0 requests for 
the device you have specified, executes the specified I/0 
commands, handles I/0 interruptions, directs error recovery 
procedures, and posts the results of the I/0 requests. 
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USING EXCP IN SYSTEM AND PROBLEM PROGRAMS 


HOW THE SYSTEM USES 





This section explains the procedures performed by the system and 
the programmer when EXCP is issued by the routines of IBM access 
methods. The additional procedures you must perform when 
issuing EXCP yourself are then described by direct comparison. 


EXCP 


When using an IBM access method to perform I/0 operations, the 
programmer is relieved of coding channel programs and 
constructing the control blocks necessary for the execution of 
channel programs. To permit I/0 operations to be handled by an 
access method, the programmer need only issue the following 
macro instructions: 


e A DCB macro instruction that produces a data control block 
(DCB) for the data set to be retrieved or stored 


e An OPEN macro instruction that initializes the data control 
sta and produces a data extent block (CDEB) for the data 
se 


& A macro instruction (for example, GET or WRITE) that 
requests I/0 operations 


Access method routines will then: 


1. Create a channel program that contains channel commands for 
the I/0 operations on the appropriate device 


2. Construct an input/output block (I0B) that contains 
information about the channel program 


3. Construct an event control block CECB) that is later posted 
with a completion code each time the channel program 
terminates 


G4. Issue an EXCP macro instruction to pass the address of the 
IOB to the routines that initiate and supervise the I/0 
operations 


The I/0 process consists of: 


5. Constructing a request queue element CRQE) for scheduling 
the request 


6. If the requestor is ina V=V address space, fixing the 
buffers so that they cannot be paged out and translating the 
requestor's virtual channel program into a real channel 
program 


7. Issuing a start subchannel (SSCH) instruction to cause the 
channel to execute the real channel program 


8. Processing I/0 interruptions and scheduling error recovery 
procedures when necessary 


9. Posting a completion code in the event control block after 
the channel program has been executed 


Note: If the requestor is an authorized program ina V=R_ 
address space, a real channel program is provided; thus, item 6 
1s not performed. 


The programmer is not concerned with these procedures and does 
not know the status of I/O operations until they are completed. 
Device-dependent operations are limited to those provided by the © 
macro instructions of the particular access method selected. 
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HOW TO USE EXCP IN PROBLEM PROGRAMS ~ 


To issue the EXCP macro instruction directly, you must follow 


the procedures that the access methods would perform, as i 


summarized in items 1 through 4 of the preceding discussion. In 
addition to constructing and opening the data control block with 
the DCB and OPEN macro instructions, you must construct a 
channel program, an input/output block, and an event control 
block before you can issue EXCP. The I/O process generally 
handles items 5 through 9. 


After issuing EXCP, you should issue a WAIT macro instruction, 
specifying the address of the event control block, to determine 
whether the channel program has terminated. If volume switching 
is necessary, you must issue an EOV macro instruction. When all 
processing of the data set has been completed, you must issue a 
CLOSE macro instruction to restore the data control block. 


All external interfaces for EXCP are compatible between MVS/370 
and MVS/XA, except for the restrictions noted below. These 
restrictions relate only to the support of virtual and real 
addresses above 16-megabyte. 


EXCP will be available to programs executing in either 24-bit or 
3l-bit addressing mode. However, in order to maintain the 
required compatibility, the following restrictions apply: 


e EXCP will only support a 24-bit virtual storage interface. 
In addition, all areas related to I/0 operations (for 
example, I/0 buffers, channel command words, IOBs, DEBs, 
appendages, and so forth), must remain 24-bit virtual 
addressable. EXCP (channel command word translator) will 
allow 24-bit virtual I/0 buffers to be fixed above 
l6-megabyte real. When a channel command word (CCW) 
references a real address above l16-megabyte, the CCW 
translator will build an indirect addressing word CIDAW) for 
that CCW. Note that this is not supported for format-1 ( 
CCWs. All virtual addresses must be below 16-megabyte. For *: 
V=R users, CCWs and IDAWs must be below l6-megabyte real. 


A 
‘ \ 
Ss we 


e Only format-0 CCWs are accepted as input. 


® All user-specified appendage routines will be given control 
in 24-bit addressing mode and must return in the same mode. 


Note: Access methods run in 24-bit addressing mode. Users 
running in 3l-bit mode must interface to the access methods by 
uSing a user-written routine that is resident below 16-megabyte 
virtual Cbecause the access methods will be able to return 
control only to a 24-bit addressable location). All addresses, 
buffers, parameters, control blocks, save areas and exit 
addresses must be below 16-megabyte virtual. All access methods 
Cexcept VSAM), for example, GET or PUT, must be called in 24-bit 
addressing mode. 


31-BIT IDAW PROGRAMMING NOTES 


A virtual channel program provided by the EXCP caller may have 
one or more CCWs with the IDA flag set and the address portion 


of these CCWs pointing to a single 4-byte IDAW. This EXCP 


function is referred to as virtual IDAWs. 

The 4-byte IDAW can contain a virtual address that ranges from 0 
t o the maximum 3l-bit address. Virtual IDAWs are supported 
on all virtual CCWs except: 


e Transfer in channel (TIC) commands. 
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° All non data-transfer type commands: for example, | 
recalibrate, rewind, set space, fold, block data check, no 
operation, control commands. | 


° Read, read backward, and sense commands, with the skip flag 
set. 


The same addressing restrictions apply to EXCPVR inputs with the 
exception that 3l-bit real data areas may be specified by the 
user-created CCWs through the use of IDAWs. All CCWs and IDAWs 
must be below l6-megabyte real. 


Only format-0 CCNs are accepted as input. 


All other areas related to the EXCP/EXCPVR I/0 operation (for 
example, CCWs, IDAWs, IOBs, DEBs, DCBs, appendages, and so 
forth) must remain 24-bit addressable. 


Note, however, that the EXCP processor will allow both 24-bit | 
pa virtual I/0 buffers to be fixed above 16~-megabyte 
real. 


HOW EXCP OPERATES IN A V=R ADDRESS SPACE 


CHANNEL PROGRAM 





User-constructed channel programs for I/0 operations of an 
authorized program ina V=R address space are not translated. 
Because the address space is V=R, any CCWs created by the user 
have correct real data addresses. (Translation would only 
re-create the user's channel program, so the CCNs are used 
directly.) 


Modification of an active channel program by data read in or by 
processor instructions is legitimate ina V=R address space, but 
not ina V=V address space. 


This section describes the channel program that you must provide 
in order to issue EXCP. The control blocks that you must either 
construct directly or cause to be constructed by use of macro 
instructions are also described. 


All areas related to the EXCP/EXCPVR I/0 operation (Cfor example, 
CCWs, IDAWs, IOBs, DEBs, DCBs, appendages, and so forth) must 
remain 24-bit addressable. 


Note, however, that the EXCP processor will allow both 24-bit 
sac virtual I/0 buffers to be fixed above l6-megabyte 
real. 


The channel program supplied by you and executed through EXCP is 
composed of CCWs on doubleword boundaries. Each channel command 
word specifies a command to be executed and, for commands 
initiating data transfer, the area to or from which the data is 
to be transferred. 


Channel command word operation codes used with specific I/0 
devices can be found in IBM publications for those devices. All 
channel command word operation codes described in these 
publications can be used. In addition, both data chaining and 
command chaining may be used. 


To specify either data chaining or command chaining, you must 
set appropriate bits in the channel command word and indicate 
the type of chaining in the input/output block. Both data and 
command chaining should not be specified in the same channel 
command word; if they are, data chaining takes precedence. 
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EXCP does not support channel programs that modify themselves, 
regardless of the method of modification: data chaining, 
command chaining, or a program to do the modification. The 
intended modification in virtual storage has no effect on the 
running real-channel program (see "Modification of a Channel 
Program during Execution™ on page 42). 





CONTROL BLOCKS 


When using EXCP, you must be familiar with the function and 
structure of the IOB, the ECB, the DCB, the DEB, and the IDANW. 
IOB and ECB fields are illustrated under "Control Block Fields" 
on page 67. DCB fields are illustrated under "Macro 
Specifications for Use with EXCP™ on page 51. The handling of 
IDAWs is described under "SIO Appendage™ on page 72 
Descriptions of these control blocks follow. 


Input/Output Block (IOB) 


The input/output block is used for communication between the 
problem program and the system. It provides the addresses of 
other control blocks, and maintains information about the 
channel program, such as the type of chaining and the progress 
of I/0 operations. You must define the input/output block and 
specify its address as the only parameter of the EXCP macro 
instruction. 


Event Control Block (ECB) 


The event control block provides you with a completion code that 
describes whether the channel program was completed with or 

without error. A WAIT macro instruction, which can be used to 
synchronize I/0 operations with the problem program, must _ 
identify the event control block. You must define the event ff ™ 
control block and specify its address in the input/output block. \ J 


Data Control Block (DCB) 


The data control block provides the system with information 
about the characteristics and processing requirements of a data 

get to be read or written by the channel program. A data 

control block must be produced by a DCB macro instruction that 
includes parameters for EXCP. If appendages are not being used, 
a short DCB is constructed. Such a DCB does not support reduced 
error recovery. You specify the address of the data control 
block in the input/output block. 


All DCBs must be located in storage that is not fetch-protected, 
or, if the task is authorized, in storage that is in the key of 
the task (CTCB KEY). 


Data Extent Block (DEB) 


The data extent block contains one or more extent entries for 
the associated data set and other control information. An 
extent defines all or part of the physical boundaries on an 1/0 
device occupied by, or reserved for, a particular data set. 

Each extent entry contains the address of a unit control block 
CUCB) that provides information about the type and location of 
an I/0 device. More than one extent entry can contain the same 
UCB address. For all I/0 devices supported by the operating 
system, the data extent block is produced during execution of 
the OPEN macro instruction for the data control block. The 
system places the address of the data extent block into the data 
control block. All DEBs must be located in storage that is not 
fetch-protected, or, if the task is authorized, in storage that 
is in the key of the task (TCB key). Only authorized tasks 
CAPF-authorized or TCB PKF=0-7) may build DEBs to be used for 
I/O operations. 
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HOW THE CHANNEL PROGRAM EXECUTES 
This section explains how the system uses your channel program 
and control blocks after you issue EXCP. 


INITIATION OF THE CHANNEL PROGRAM 


By issuing EXCP, you request the execution of the channel 
program specified in the input/output block. The I/0 process 
validates the request by checking certain fields of the control 
blocks associated with this request. If the I/O process detects 
invalid information in a control block, it initiates abnormal 
termination procedures. 


The EXCP processor gets: 


e The address of the data control block from the input/output 


block 

® The address of the data extent block from the data control 
block 

e The address of the unit control block from the data extent 
block . 


It places the IOB, TCB, DEB, and UCB addresses and other 
information about the channel program into an area called a 
request queue element (CRQE). CUnless you are providing 
appendage routines (described under "Appendages™ on page 43) you 
should not be concerned with the contents of RQEs.) 


If you have provided a start I/0 (SIO) appendage, the EXCP 
processor now passes control to it. The return address from the 
SIO appendage determines whether the EXCP processor must: 


6 Execute the I/0 operation normally, or 
e Skip the I/0 operation. 


For a description of the SIO appendage and its linkage to the 
EXCP processor, see "Appendages™ on page 43. 


If you are issuing EXCP from a V=V address space, the channel 
program you construct contains virtual addresses. Because 
channel subsystems cannot use virtual addresses, the EXCP 
processor must: 


e Translate your virtual channel program into one that uses 
only real addresses. 


® Fix in real storage the pages used as 1/0 areas for the data 
transfer operations specified in your channel program. 


The EXCP processor builds the translated Creal) channel program 
in a portion of real storage. 


For direct access devices, specify the seek address in the 
input/output block. The I/0 supervisor constructs a command 
chain to issue the seek and the set file mask specified in the 
data extent block, and to pass control to your real channel 
program. 


If your channel program begins with a locate~record command, the 
I’0 process builds a define-extent command and passes control to 
your real channel program. CYou cannot issue the initial seek, 
set file mask, or define extent. The file mask is set to 
prohibit seek-cylinder commands, or, if space is allocated by 
tracks, seek-head commands. If the data set is open for INPUT, 
write commands are also prohibited. ) 


For a magnetic tape device, the I/O supervisor constructs a 
command chain to set the mode specified in the data extent block 
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and passes control to your real channel program. CYou cannot 
set the mode yourself.) 


If the I/0 device is other than a direct access device or a 
magnetic tape device, the I/0 supervisor then places the 
starting CCW of the channel program into the operation request 
block CORB) and issues a start subchannel CSSCH) instruction. 





MODIFICATION OF A CHANNEL PROGRAM DURING EXECUTION 


Any problem program that modifies an active channel program with 
processor instructions or with data read in by an I/0 operation 
must be run in a V=R address space. It cannot run ina V=V 
address space because of the channel program translation 
performed by the I/0 supervisor. (In a V=V address snace; an 
attempt to modify an active channel program affects only the 
virtual image of the channel program, not the real channel 
program being executed by the channel subsystem. ) 


A program of this type can be changed to run in a V=V address 
space by issuing another EXCP macro for the modified portion of 
the channel program. 


COMPLETION OF EXECUTION 


The system considers the channel program completed when it 
receives an indication of a channel-end condition in the 
subchannel status word (CSCSW). Unless a channel-end or 
abnormal-end appendage directs otherwise, the request queue 
element for the channel program is made available, and a 
completion code is placed into the event control block. The 
completion code indicates whether errors are associated with 
channel end. If device end occurs simultaneously with channel 
end, errors associated with device end (that is, unit exception 
or unit check) are also accounted for. 


ie 


If device end occurs after channel end and if an error is 
associated with device end, the completion code in the event 
control block does not indicate the error. However, the status 
of the unit and channel is saved by the I/0 supervisor for the 
device, and the UCB is marked as intercepted. The input/output 
block for the next request directed to the I/O device is also 
marked as intercepted. The error 1s assumed to be permanent, 
and the completion code in the event control block for the 
intercepted request indicates interception. The DCBIFLGS field 
of the data control block is also flagged to indicate a 
permanent error. Note that, if a write-tape-mark or 
erase-long-gap CCW is the last or only CCW in your channel 
program, the I/0 process will not attempt recovery procedures 
for device end errors. In these circumstances, command chaining 
a NOP CCW to your write-tape-mark or erase-long-gap CCW ensures 
initiation of device-end error recovery procedures. 


To be prepared for device-end errors, you should be familiar 
with device characteristics that can cause such errors. After 
one of your channel programs has terminated, you should not 
release buffer space until you have determined that your next 
request for the device has not been intercepted. You may 
reissue an intercepted request. 


INTERRUPTION HANDLING AND ERROR RECOVERY PROCEDURES 


An I/0 interruption allows the processor to respond to signals 
from an I/0 device that indicate either termination of a phase 
of I/0 operations or external action on the device. A ard ted 
explanation of I/0 interruptions is contained in 

For descriptions of eatcrructice by 
specific devices, see the IBM publications for each device. 





If error conditions are associated with an interruption, the I/0 
supervisor schedules the appropriate device-dependent error 
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routine. The channel subsystem is then restarted with another 
request that is not related to the channel program in error. 
(The following paragraphs discuss "related™ channel programs. ) 
If the error recovery procedures fail to correct the error, the 
system places ones in the first two bit positions of the 
DCBIFLGS field of the data control block. You are informed of 
the error by an error code in the event control block. 


If a channel program depends on the successful completion of a 
previous channel program Cas when one channel program retrieves 
data to be used in building another), the previous channel 
program is called a "related™ request. Such a request must be 
identified to the EXCP processor. To find out how to do this, 
see "Input/Output Block CIOB) Fields®™ on page 67. 


If a permanent error occurs in the channel program of a related 
request, the EXCP processor removes the request queue elements 
for all dependent channel programs from their queue and makes 
them available. 


The related request queue (RRQ) reflects the order in which 
request queue elements are removed from their queue. 


For all requests dependent on the channel program in error, the 
system places completion codes into the event control blocks. 
The DCBIFLGS field of the data control block is also flagged. 
Any requests for a data control block with error flags are 
posted complete without execution. To reissue requests 
dependent on the channel program in error, you must reset the 
first two bits of the DCBIFLGS field of the data control block 
a eli You then reissue EXCP for each channel program 
esired. 


With the IBM 3800 Printing Subsystem, a cancel key or a 
system-restart-required paper jam causes both a lost data 
indicator to be set in DCBIFLGS and a lost page count and 
channel page identifier to be stored in the ane extension. (See 


» ISOZE Data Areas, and 
u [ -yed J ] a 


An appendage is a programmer-written routine that provides 
additional control over I/0 operations. By using appendages, 
you can examine the status of I/0 operations and determine the 
actions to be taken for various conditions. An appendage may 
receive control when one of the following occurs: 

® EXCP SVC 

° Program-controlled interrupt 

e End of extent 

® Channel end 

6 Abnormal end 


Appendages get control in supervisor state, receiving the 
following pointers from the EXCP processor: 


e Register 1: Points to the request queue element for the 
channel program. 


® Register 2: Points to the input/output block CIOB). 
e Register 3: Points to the data extent block CDEB). 
e Register 4: Points to the data control block CDCB). 


e Register 6: Points to the seek address if control is given 
to an end-of-extent appendage. 
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Register 7: Points to the unit control block CUCB). 


Register 13: Points to a l16-word area you can use to save 


input registers or data. 


Register 14: Points to the location in the EXCP processor 
where control is to be returned after execution of an 
appendage. When returning control to the EXCP processor, 
you may use displacements from the return address in 
register 14. Allowable displacements are summarized in 
Figure 12 and described later for each appendage. 


Register 15: Points to the entry point of the appendage. 


The processing done by appendages is subject to these 
requirements and restrictions: | 


The types of appendages are described in the following sections, 


Register 9, if used, must be set to binary zeros before 
control is returned to the system. All other registers, 
except those indicated in the descriptions of each 
appendage, must be saved and restored if they are used. 
Figure 12 summarizes register conventions. 


No SVC instructions or instructions that change the status 


of the system (for example, WTO, LPSW, or any privileged 


instructions) can be issued. 


Loops that test for the completion of I/0 operations must 
not be used. 


Storage used by the I/0 supervisor or EXCP processor must 
not be altered. 


with explanations of when they are created, how they return 


control to the system, 


and which registers they may use without 


Saving and restoring their contents. 


Note: 


All user-specified appendages will be given control in 


24-bit addressing mode and must return in the same mode. 


Entry Points, 


Returns Available Work Registers! 
Reg 14 + 0 Return 

Reg 14 + 4 Skip Reg. 10, ll, 12, and 13 
Reg 14 + 8 Try Again 

Reg 14 + 0 Normal Reg. 10, ll, and 13 

Reg 14 + G Skip 

Reg 14 + 0 Normal Reg. 10, ll, 12, and 13 
Reg 14 + 0 Normal Reg. 10, ll, 12, and 13 
Reg 19 + G Skip 

Reg 149 + 8 Re-EXCP 

Reg 14 + ] By-Pass 

Reg 14 + 0 Normal 

Reg 194 + G Skip Reg. 10, ll, 12, and 13 
Reg 14 + 8. Re-~EXCP 

Reg 14 + 1 By-Pass 


Note to Figure 12: 


1 


Returns, and Available Work Registers for Appendages 


Certain register conventions for passing parameters from 


appendages to the EXCP processor must be followed. 


These 


conventions are described in the individual appendage 


descriptions. 
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START-I70 (SIO) APPENDAGE 


Unless an error recovery procedure is in control, the EXCP 
processor passes control to the SIO appendage just before the 
EXCP processor translates your channel program. 


Optional return vectors give the I/0 requestor the following 
choices: 


Reg. 14 + 0 
Normal return. Normal channel program translation and 
initiation of I/70 


Reg. 14 + 4 
Skip the I/O operation. The channel program is not posted 
complete, but the request queue element is made available. 
You may post the channel program as follows: 


1. Save necessary registers. 


2. Put the address of the post routine (found at CVTOPTOI1 
in the communications vector table) in register 15. 


3. Place the ECB address from the IOB in register l1l. 


G. Set the completion code in register 10. These are the 
four bytes of an ECB. 


5. Go to the post routine pointed to by the CVT, using 
BALR 14, 15. 


PROGRAM-CONTROLLED INTERRUPTION (PCI) APPENDAGE 


This appendage is entered at least once if the channel finds one 
or more PCI bits on in a channel program. It may be entered as 
many times as the channel finds PCI bits on. Before the 
appendage is entered, the contents of the subchannel status word 
are placed in the "channel status word" field of the 
input/output block. 


A PCI appendage will be reentered if an error recovery procedure 
is retrying a channel program in which a PCI bit is on. The IOB 
error flag is set when the error recovery procedure is in 
control CIOBFLAG1 = X'20'). (For special PCI conditions 
encountered with command retry, see "Channel Programming 
Considerations" on page 50.) 


To post the channel program from a PCI appendage, the procedure 
described for the start-I/0 appendage is used if the step is 
running ADDRSPC=VIRT or an authorized program 1s running VER. 
If the step is running ADDRSPC=REAL and an authorized program 
issued the EXCP request or if SVC LIGCEXCPVR) was issued, the 
PCI appendage uses real storage addresses, and the following 
procedure is used to post the channel program from the PCI 
appendage. 


1. Put the completion code in register 10 and place X'80!" in 
gis ecto byte to indicate the key is in register 0 
step : 


2. Put X'80" in the high-order byte of register 1l1l and the 
address of the ECB in the low-order bytes. 


3. Put X*80* in the high-order byte of register 12 and the 
address of a BR 14 instruction in the low-order bytes. This 
BR 14 must be in storage addressable from any address space 
(for example, CVTBRET) and must be in storage addressable by 
24% bits. Note that only registers 9 and 14 are restored 
when you use this option. 
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4. Put.the address of the ASCB in register 13. 


The next two paragraphs describe how to obtain the ASCB 
address and are followed by sample instructions to : 
illustrate the procedure. 


Get the SRB address associated with. the I/0 operation from 
the RQE field, RQESRB (the RQE address was in register 1 
when the appendage was given control). Get the IOSB address 
from SRBPARM. From that IOSB, get the identifier field, 
IOSASID. Multiply IOSASID by 4. 


Get the pointer to the ASVT Caddress space vector table) 
found at CVTASVT. The address of the ASCB can be found in 
the ASVT, using the field ASVTENTY-4 indexed by the value 
calculated in the above paragraph. 


eae RQE, 1 


Y,RQESRB | 
USING SRBSECT,Y 
LH Y,»SRBPARM 
USING IOSB,Y | 
LH Y,TIOSASID 
SLA Y;2 
USING CVT ,X 
L X,CVTASVT 
USING ASVT,X 
L 13,ASVTENTY-4CY) 


Note: X and Y are work registers. 
5. Put the requestor's key in register 0. 


6. Put the address of the post routine (found at CVTOPTO1] in 
the communications vector table) in register 15. 


7. Go to the post routine using BALR 14,15. Upon return, only 
registers 9 and 14 are valid. For more information on the 
POST Pedr aibied see j 


This procedure can be used even if the PCI appendage uses 
ae storage addresses, but performance may be slightly 
slower. 


To return control to the EXCP processor for normal interruption 
processing, use the return address in register 14. 


APPENDAGE 


This appendage is entered when the seek address specified in the 
input/output block is outside the allocated extent limits 
indicated in the data extent block. 


If you use the return address in register 14 to return control 
to the system, the abnormal-end appendage is entered. An 
end-of-extent error code (X'42') is placed in the "ECB code"™ 
oe of the input/output block for subsequent posting in the 


You may use the following optional return addresses: 

¢ Contents of register 14 plus 4: The channel program is 
posted complete; its request element is returned to the 
available queue. 


e Contents of register 14 plus 8: The request is tried again. 


You may use registers 10 through 13 in an end-of-extent 
appendage without saving and restoring their contents. 
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Note: If an end-of-cylinder or file-protect condition occurs; 
the EXCP processor updates the seek address to the next higher 
pos cylinder or track address and reexecutes the request. If the 
( | new seek address is within the data set's extent, the request is 
executed; if the new seek address is not within the data set's 
extent, the end-of-~extent appendage is entered. If you want to 
try the request in the next extent, you must move the new seek 
address to the location pointed to by register 6. 


If a file protect is caused by a full seek Ccommand code=07) 
embedded within a channel program, the request is flagged as a 
permanent error, and the abnormal end appendage is entered. 





CHANNEL-END (CHE) APPENDAGE 


This appendage is entered when a channel end (CHE), unit 
exception CUEX) with or without channel end or when channel end 
with wrong-Length record CWLR) occurs without any other 
abnormal-end conditions. 


If you use the return address in register 14 to return control 
to the EXCP processor, the channel program is posted complete, 
and its request element is made available. In the case of unit 
exception or wrong-Length record, the error recovery procedure 
is performed before the channel program is posted complete, and 
the IOBIOERR flag (X'04') in IOBFLAGI1 is set on. The CSW status 
may be obtained from the IOBCSW field. 


If the appendage takes care of the wrong-length record or unit 
| exception or both, it may turn off the IOBIOERR flag in IOBFLAGI 
and return normally. The event will then be posted as complete 
Ccompletion code X'7F* under normal conditions, taken from the 
| high-order byte of the IQBECBCC field). If the appendage 
returns normally without resetting the IOBIOERR flag to zero, 
- the request will be routed to the associated device error 
oe recovery procedure CERP), and the abnormal-end appendage will 
( then be entered with the completion code in IOBECBCC set to 
X'41' if the ERP could not correct the error. (See Step 1 of 
"Abnormal-End CABE) Appendage™ on page 48.) 


You may use the following optional return addresses: 


e Contents of register 14 plus 4: The channel program is not 
posted complete, but its request element is made available. 
You may post the channel program by using the calling 
sequence described under the start-I/0 appendage. This is 
especially useful if you want to post an ECB other than the 
ECB in the input/output block. 


e Contents of register 14¢ plus 8: The channel program is not 
posted complete, and its request element is placed back on 
the request queue so that the I/0 operation can be retried. 
For correct reexecution of the channel program, you must 
reinitialize the IOBFLAG]1, IOBFLAG2, and IOBFLAG3 fields of 
the input/output block and set the "Error Counts" field to 
zero. As an added precaution, the IOBSENSO, IOBSENSI, and 
IOBCSW fields should be cleared. 


e Contents of register 14 plus 12: The channel program is not 
posted complete, and its request element is not made 
available. (This return must be used if, and only if, the 
appendage has passed the RQE to the exit effector for use in 
scheduling an asynchronous routine. For information on the 
exit effector, see e L133 : 


You may use registers 10 through 13 in a channel-end appendage 
without saving and restoring their contents. 
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ABNORMAL-END (ABE) APPENDAGE 


This appendage may be entered on abnormal conditions, such as 
unit check, unit exception, wrong-length indication, program 
check, protection check, channel data check, channel control 
check, interface control check, chaining check, out-of-extent 
error, and intercept condition (that is, device end error). It 
may also be entered when an EXCP is issued for a request queue 
element that has already been purged. 








1. When this appendage is entered because of a unit exception 
or wrong-~length record indication or both, IOQBECBCC is set 
to X'41'. For further information on these conditions, see 
"Channel-End CCHE) Appendage" on page 47. : 


id a om de 
When the appendage is entered because sf 


error, the IQBECBCC is set to X‘'42"'. 


3. When this appendage is entered with IOBECBCC set to X'4B', 
1t is because of: 


INQ 





a. The tape error recovery procedure CERP) encountering an 
unexpected load point, or 


b. The tape error recovery procedure CERP) finding zeros in 
the command address field of the CSW. 


G. When the appendage is first entered because of an intercept 
condition, the IOBECBCC is set to X'7E". If it is then 
determined that the error condition is permanent, the 
appendage will be entered a second time with the IOBECBCC 


set to X'44¢". The intercept condition signals that an error 
was detected at device end after channel end on the previous 
request. 


5. When the appendage is entered because of an EXCP being 
issued to an already purged request queue element, this 
request will enter the abnormal end appendage with the 
IOBECBCC set to X'48'. This applies only to related 
requests. . 


a a 
ae, 


6. If the appendage is entered with IOBECBCC set to X'7F*, it 
may be because of a unit check, program check, protection 
check, channel data check, channel control check, interface 
control check, or chaining check. If the IOBECBCC is X'7F', 
it is the first detection of an error in the associated 
channel program. If the IOBEX (X'046") flag (bit 5 of the 
IOBFLAG1) is on, the IQBECBCC field will contain a X'4l1'!, 
X'*G2', X*GB", X*GB', or X'*GF' in hexadecimal, indicating a 
permanent I/O error. 


To determine if an error is permanent, you should check the ! 
IOBECBCC field of the IOB. To determine the type of error, | 
check the channel status word field and the sense information in : 
the IOB. However, when the IOBECBCC is X'42', X'G8", or X'GF', 
these fields are not applicable. For X"'"44', the CSW is 

pa but the sense is valid only if the unit check bit is 
set. | 


If you use the return address in register 14 to return control 
to the system, the channel program is posted complete, and its 
request element is made available. You may use the following 
optional return addresses: 


e Contents of register 14 plus 4: The channel program is not 
posted complete, but its request element is made available. 
You may post the channel program by using the calling 
sequence described under the start-I/0 appendage. 


e Contents of register 14 plus 8: The channel program is not 
posted complete, and its request element is placed back on 
the request queue so that the request can be retried. 
Reinitialize the IOBFLAG]1, IOBFLAG2, and IOBFLAG3S fields of 
the input/output block and set the IOBERRCT field to zero. 
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As an added precaution, clear the IOBSENSO, IOBSENSI, and 
IOBCSW fields. 


e Contents of register 14 plus 12: The channel program is not 
posted complete, and its request element is not made 
available. (This return must be used if, and only if, the 
appendage has passed the RQE to the exit effector for use in 
scheduling an asynchronous routine. ) 


You may use registers 10 through 13 in an abnormal-end appendage 
without saving and restoring their contents. 





Before your appendages can be executed, they must become members 
of either the SYS1.LPALIB or SYS1.SVCLIB data set. There are 
two ways to put appendages into SYSI1.LPALIB or SYS1.SVCLIB: 

They can be included at system generation using the DATASET 
macro instruction Ca full explanation appears in 


installation 
tion), or they can be link-edited into SYS1.LPALIB 


aystem Generation 

or SYSI]1.SVCLIB after the system has been generated. Each 
appendage must have an 8-character member name, the first six 
characters being IGGO19 and the last two being anything in the 
range from WA to Z9. Note, however, if your program runs in a 
V=R address space and uses a PCI appendage, the PCI appendage 
and any appendage that the PCI appendage refers to must be 
placed in either SYS1.SVCLIB or the fixed link pack area CLPA). 
For information on providing a list of programs to be fixed in 
storage, see Initialization and Tuning. 


THE AUTHORIZED APPENDAGE LIST CIEAAPPOO) 


If an "unauthorized" program opens a DCB to be used with an EXCP 
macro instruction, the names of any appendages associated with 
the DCB must be listed in the IEAAPP00 member of SYS1.PARMLIB. 
CAn “unauthorized™ program is one that runs ina protection key 
greater than 7 and has not been marked as authorized by the 
Authorized Program Facility. ) 


If your appendages were put in SYSI1.LPALIB or SYS1.SVCLIB at 
system generation, their names are automatically put in 
ITEAAPPO0O0. If your appendages were added to SYS1.LPALIB or 
SYS1.SVCLIB after system generation, you can add IEAAPPO00 to 
SYS1.PARMLIB and put the names of the appendages in it in one 
job step with the IEBUPDTE utility. 


Here is an example of JCL statements and IEBUPDTE input that 
will add IEAAPP00 to SYS1.PARMLIB and put the names of one EOE 
appendage, two SIO appendages, two CHE appendages, and one ABE 
appendage in IEAAPPOO: 


// JOB a: te 

1/ EXEC PGM= js ae 

//SYSPRINT DD SYSOUT= 

//SYSUT2 DD DSN= SYSi. PARMLIB,DISP=OLD 
S/SYSIN DD X 

if ADD NAME=ITEAAPP00,LIST=ALL 
EOEAPP WA, 


SIOAPP X1,X2, 
CHEAPP 23,24, 
ABEAPP 22 

7% 


Note the following about the IEBUPDTE input: 


® The type of appendage is identified by six characters that 
begin in column 1. EQEAPP identifies an EOE appendage, 
SIOAPP an SIO appendage, CHEAPP a CHE appendage, and ABEAPP 
an ABE appendage. (The PCI appendage identifier, PCIAPP, is 
Saba because the example adds no PCI appendage name to 
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® Only the last two characters in an appendage" Ss name are 
specified, beginning in column 8 


@ Each statement that identifies one or more appendage names 
ends ina comma, except the last statement. 





You can also use IEBUPDTE to add appendage names later or to 
delete appendage names. Here is an example of JCL statements 
and IEBUPDTE input that adds the names of a PCI. and an ABE 
appendage to the ITEAAPP00 appendage list that was created in the 
preceding example, and deletes the name of an SIO appendage from 


that list: 
11 JOB... 
11 EXEC PGM=IEBUPDTE 
//SYSPRINT DD SYSOUT=A 
//SYSUT2 DD DSN=SYS1.PARMLIB, DISP=OLD 
//SYSIN- sé x 
7 REPL NAME=IEAPP00,LIST=ALL 
PCLAPP Yl, | | 
EOEAPP WA, 


SIOAPP X1,X2, 
CHEAPP 23,264, 
ABEAPP 22,24 
i 
Note the following about the IEBUPDTE input: 
@ The command to IEBUPDTE in this case is REPL Creplace). 


@ All the appendage names that are to remain in IEAAPPO0OO are 
repeated. 


@ IGG019Z4 is both a CHE and an ABE appendage. 





—- \ 
ae 


Command retry is a function of the channel supporting the IBM 
2305-2, 3330/3333, 3340/3344, 3350, 3375, and 3380 direct access 
devices. When the channel subsystem receives a retry request, 
it repeats the execution of the CCW, requiring no additional 
input/output interrupts. For example, a control unit may 
initiate a retry procedure to recover from a transient error. 


A command retry during the execution of a channel program may 
cause any of the following conditions to be detected by the 
initiating program: | 


e Modifying CCWs: A CCW used in a channel program must not be 
modified before the CCW operation has been successfully 
completed. Without the command retry function, a command 
was fetched only once from storage by a channel. Therefore, 
a program could determine through condition codes or program 
controlled interruptions CPCI) that a CCW had been fetched 
and accepted by the channel. This permitted the CCW to be 
modified before reexecution. With the command retry 

function, this cannot be done, because the channel will 
fetch the CCW from storage again on a command retry 
sequence. In the case of data chaining, the channel will 
sated commands starting with the first CCW in the data 
chain. 


e Program Controlled Interrupts (PCI): A CCW containing a PCI 
flag may cause multiple program-controlled interrupts to 
occur. This happens if the PCI-flagged CCW was retried 
during a command retry procedure and if a PCI could be 
generated each time the CCW is reexecuted. 


@ Residual Count: If a channel program is prematurely 
terminated during the retry of a command, the residual count 
in the channel status word (CSW) will not necessarily 
indicate how much storage was used. For example, if the 
control unit detects a "wrong~-length record” error 
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condition, an erroneous residual count is stored in the CSW 

until the command retry is successful. When the retry is 
an successful, the residual in the CSW reflects the correct 

( length of the data transfer. 


e Command Address: When data chaining with command retry, the 
CSW may not indicate how many CCWs have been executed at the 
time of a PCI. For example: 


CCW# Channel Program 


1 Read, data chain 

2 Read, data chain 

3 Read, data chain, PCI 
& Read, command chain 


In this example, assume that the control unit signals 
command retry on Read #3 and the processor accepts the PCI 
after the channel resets the command address to Read #1 
because of command retry. The CSW stored for the PCI will 
contain the command address of Read #1 when the channel has 
actually progressed to Read #3. 


e Testing Buffer Contents on Data Read: Any program that tests 
a buffer to determine when a CCW has been executed and 
continues to execute based on this data may get incorrect 
results if an error is detected and the CCW is retried. 


MACRO SPECIFICATIONS FOR USE WITH EXCp 


If you are using the EXCP macro instruction, you must also use 
DCB, OPEN, CLOSE, and, in some cases, the EOV macro instruction. 
The parameters of these macro instructions and the EXCP macro 
instructions are explained here. A diagram of the data control 
- block is included with the description of the DCB macro 
( instruction. 


DEFINING DATA CONTROL BLOCKS FOR EXCP (DCB) 


The EXCP form of the DCB macro instruction produces a data 
control block that can be used with the EXCP macro instruction. 
You must issue a DCB macro instruction for each data set to be 
processed by your channel programs. Notation conventions and 
format illustrations of the DCB macro instruction ae in 


: c oO er ‘ 
parameters that apply to EXCP may be divided into four 
categories, depending on the following portions of the data 
control block that are generated when they are specified: 


e Foundation block. This portion is required and is always 12 
bytes in length. You must specify two of the parameters in 
this category. 


e EXCP interface. This portion is optional. If you specify 
any parameter in this category, 20 bytes are generated. 


e Foundation block extension and common interface. This 
portion is optional and is always 20 bytes in length. If 
this portion is generated, the device-dependent portion is 
also generated. 


® Device dependent. This portion is optional and is generated 
only if the foundation block extension and common interface 
portion is generated. Its size ranges from 4 to 20 bytes, 
depending on specifications in the DEVD parameter. However, 
if you do not specify the DEVD parameter Cand the foundation 
extension and common interface portion is generated), the 
maximum 20 bytes for this portion are generated. 





Some of the procedures performed by the system when the data 
control block is opened and closed (such as writing file marks 
for output data sets on direct access volumes) require 
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information from optional data control block fields. You should 

make sure that the data control block is large enough to provide 

reg Aa necessary for the procedures you want the system 
o handle. 








Figure 13 on page 53 shows the relative position of each portion 
of an opened data control block. The fields corresponding to 
each parameter of the DCB macro instruction are also designated, 
with the exception of DDNAME, which is not included in a data 
control block that has been opened. The fields identified in 
parentheses represent system information that is not associated 
with parameters of the DCB macro instruction. 


Sources of information for data control block fields other than 

the DCB macro instruction are data definition (DD) statements, 

data set labels, and data centre! block modification routines. | 
You may use any of these sources to specify DCB parameters. | 
However, if a particular portion of the data control block is | 
not generated by the DCB macro instruction, the system does not 
accept information intended for that portion from any 
alternative source. 


You may provide symbolic names for the fields in one or more 
EXCP DCBs by coding a DCBD macro to generate a dummy control 
section (CDSECT). To map the common interface, foundation block 
extension, and foundation block, you code DSORG=XE. To map the 
foundation block and EXCP interface, you code DSORG=XA. You may 
code DSORG=CXA,XE) to map both. For further information, see 
bata Acdminietration: Mac Ins tj Ref 


Foundation Block Parameters 


DDNAME=symbol 
The name of the data definition (DD) statement that 
describes the data set to be processed. This parameter 
must be given. 


MACRF=(E) 
The EXCP macro instruction is to be used in processing the 
data set. This operand must be coded. 


REPOS={V1N} 
Magnetic tape volumes: This parameter indicates to the 
dynamic device reconfiguration CDDR) routine whether the 
user 1s Keeping an accurate block count. If the user is 
Keeping an accurate block count, the DDR routine can 
attempt to swap the volume. (You must maintain the block 
count in the DCBBLKCT field.) 


es 


Y—The user is Keeping an accurate block count, and the DDR 
routine can attempt to swap the volume. 


N——The block count is unreliable, and the DDR routine 
cannot and will not attempt to swap the volume. 


If the operand is omitted, N is assumed. 


EXCP Interface Parameters 


EOEA= 
2-byte identification of an EOE appendage that you have 
entered into SYSI]1.LPALIB or SYS1.SVCLIB. 


PCIA= 
2-byte identification of a PCI appendage that you have 
entered into SYS1.LPALIB or SYS1.SVCLIB. 


SIOA=symbol 
— 2@-byte identification of a SIO appendage that you have 
entered into SYSI1.LPALIB or SYSI1.SVCLIB. 
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—. block varies in length and format according to 


( | | The device-dependent portion of the data control | | 
> 


specifications in the DSORG and DEVD parameters. Device 
Illustrations of this portion for each device Dependent 
type are included in the description of the DEVD 

parameter. 





IOBAD 


32 BFTEK, 
BFALN EODAD “| Foundation 
> Block 
| Extension 
36 
RECFM EXLST 
G0 


CTIOT) MACRF 


2G > Common 
BUFL DSORG Interface 


Foundation 


> 
CIFLGS) (DEB Address) | Block 
| 


44 


8 
COFLGS) Reserved 


( } OPTCD a 


56 
Reserved 


EXCP 
Interface 


EOEA PCIA 


4 
SIOA 
68 


XENDA Reserved 


Figure 13. Data Control Block CDCB) Format for EXCP (After OPEN) 


CENDA=symbol 
2-byte identification of a CHE appendage that you have 
entered into SYS]1.LPALIB or SYSI.SVCLIB. 


XENDA=symbol 
2-byte identification of an ABE appendage that you have 
entered into SYS]1.LPALIB or SYS1.SVCLIB. 


OPTCD=Z 
indicates that, for magnetic tape Cinput only), a reduced 
error recovery procedure (5 reads only) will occur when a 
data check is encountered. It should be specified only 
when the tape is Known to contain errors and the 
application does not require that all records be processed. 
Its proper use would include error frequency analysis in 
the SYNAD routine. Specification of this parameter will 
also cause generation of a foundation block extension. 
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This parameter is ignored unless it was selected at system 


generation. 


IMSK=value 


Any a jee ot eot on indicates that the system will not use 


IBM-supplied 


error routines. 


Foundation Block Extension and Common Interface Parameters 


EXLST paddress 


the address of an exit list that you have written for 
exception conditions. The format of this exit list is 


given in 


EQDAD=address 


mi 


the address of your end-of- data-set routine for input data 
sets. If this routine is not available when it is 
required, the task is abnormally terminated. 


DSORG={PS|PO|DA|IS} 


the data set 


organization Cone of the following codes). 


Each code indicates that the format of the device-dependent 
portion of the data control block is to be similar to that 
generated for a particular access method: 


Code DCB Format for 


PS QSAM or BSAM 
PO BPAM | 
DA BDAM 

IS QISAM or BISAM 


For direct access devices, if you specify PS or PO, you 
must maintain the following fields of the device-dependent 
portion of the data control block so that the system can 


write a file 


mark for output data sets: 


e The track balance CDCBTRBAL) field that contains a 
2-byte binary number that indicates the remaining 
number of bytes on the current track. This number can 
be obtained from the system track algorithm routine. 


e The full 


disk address (CDCBFDAD) field that indicates 


the location of the current record. The address is in 


the form 


These fields 
used by Open 
is done only 
these fields 


MBBCCHHR. 


are written into the format-l DSCB and are 
routines for staging MSS data sets. Staging 
up through the last cylinder specified by 

if the data set is reopened for OUTPUT, INOUT, 


OUTIN, OUTINX, or EXTEND. 


If you specify PO for a direct access device, the DCBDIRCT 
field will not be updated. Therefore, you should be 


careful when 


IOBAD=address 


using EXCP with the STOW macro. 


the address of an input/output block (IOB). If a pointer 
to the current IOB is not required, you may use this field 
for any purpose. 


The following parameters are not used by the EXCP routines. 
They provide additional information that the system will store 
for later use by access methods that read or update the data 


set. 


RECFM=code 


the record format of the data set. Record Hag codes are 
U = ps ~ 


given in 
When writing 





“a eer gers ae oa or read later, RECFM, LRECL, and 


BLKSIZE should be specified to identify the data set 


attributes. 
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LRECL and BLKSIZE can only be specified in a 



































DD statement, because these fields do not exist in a DCB 
used by EXCP. 


BFTEK={S|E} 
the buffer technique, either simple or exchange. 


BFALN={F|D} 
the word boundary alignment of each buffer, either fullword 
or doubleword. 


BUFL= 
Se nas in bytes of each buffer; the maximum length is 


BUFNO= 
the number of buffers assigned to the associated data set; 
the maximum number is 255. 


BUFCB=address 
the address of a buffer pool control block, that is, the 
8-byte field preceding the buffers ina buffer pool. 


Device-Dependent Parameters 


DEVD=code 
the device in which the data set may reside. The codes are 
listed in order of descending space requirements for the 
data control block: 


Code Device 

DA Direct access 
TA Magnetic tape 
PR Printer 

PC Card punch 

RD Card reader 


Note: For MSS virtual volumes, DA should be used. 


If you do not want to select a specific device until job setup 
time, you should specify the device type requiring the largest 
area; that is, DEVD=DA. 


The following diagrams illustrate the device~dependent portion 
of the data control block for each combination of device type 


specified in the DEVD parameter and data set organization 


specified in the DSORG parameter. Fields that correspond to 
device-dependent parameters in addition to DEVD are indicated by 
the parameter name. For special services, you may have to 
maintain the fields shown in parentheses. The special services 
are explained in the note that follows the diagram. 
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Device-dependent portion of data control block when DEVD=DA and 


Ww 
Reserved DCBFDAD 


3 
DCBDVTBL 


16 17 18 
DCBKEYLE DCBDEVT DCBTRBAL 





For output data sets, the system uses the contents of the full 
disk address (DCBFDAD) field, plus one, to write a file mark 
when the data control block is closed, provided the track 
balance CDCBTRBAL) field indicates that space is available. If 
DCBTRBAL is less than 8, the file mark is written on the next 
sequential track. You must maintain the contents of these two 
fields yourself if the system is to write a file mark. OPEN 
will initialize DCBDVTBL and DCBDEVT. 


Device-dependent portion of data control block when DEVD=DA and 
DSORG=DA: yes 


16 18 
DCBKEYLE Reserved 


Device-dependent portion of data control block when DEVD=TA and 
DSORG=PS: 


Ia. 









DCBBLKCT 


The system uses the contents of the block count CDCBBLKCT) field 
to write the block count in trailer labels when the data control 
block is closed or when the EOV macro instruction is issued. 

You must maintain the contents of this field yourself if the 
system is to have the correct block count. (CNote: The I/0 
supervisor increments this field by the contents of the IOBINCAM 
field of the IOB at the completion of each I/0 request.) 


When using EXCP to process a tape data set open at a checkpoint, 

you must be careful to maintain the correct count; otherwise, 

the system may position the data set incorrectly when restart 

occurs. If REPOS=Y, the count must be maintained by you for 
repositioning during dynamic device reconfiguration. ™ 
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Device-~dependent portion of data control block when DEVD=PR and 
DSORG=PS: 


( 7 16 18 
DCBPRTSP Reserved 


Device-dependent portion of data control block when DEVD=PC or 
RD and DSORG=PS: 


18 
DCBMODE, DCBSTACK Reserved 


_ 
ON 


The following DCB operands pertain to specific devices and may 
be specified only when the DEVD parameter is specified. 


KEYLEN=length 
for direct access devices, the length in bytes of the key 
of a physical record, with a maximum value of 255. When a 
block is read or written, the number of bytes transmitted 
is the key length plus the record length. 


DEN=value 


for magnetic tape, the tape recording density in bits per 
inch: 


7-Track Density | 9-Track Density 


a 


NRZI—Non-return-to-zero change to ones recording 
PE—-phase encoded recording 
GCR—group coded recording 






If this parameter is omitted, the highest density available 
on the device is assumed. | 


TRTCH=value 


for 7-track magnetic tape, the tape recording technique: 


Value Tape Recording Technique 


C Data conversion feature is available. 
E Even parity is used. CIf omitted, odd parity is 
assumed. ) | 
T BCDIC to EBCDIC translation is required. 
MODE=value 


for a card reader or punch, the mode of operation. Either 
C Ccolumn binary mode) or E CEBCDIC code) may be specified. 


STACK=value 
for a card punch or card reader, the stacker bin to receive 
cards, either 1 or 2 
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PRTSP=yvalue 


for a printer, the line spacing, either 0, 1, 2, or 3. 





DSORG Parameter of the DCBD Macro 


In addition to. the operands described in Data Administration: 
for the DSORG parameter of the DCBD 
macro, you may specify the following operands. 


DSORG= 


XA specifies a DCB with the EXCP interface section 
Cincluding appendage names) 


XE specifies a DCB With the foundation block extension 


INITIALIZING DATA CONTROL BLOCKS (OPEN) 


The OPEN macro instruction initializes one or more data control 
blocks so that their associated data sets can be processed. You 
must issue OPEN for all data control blocks that are to be used 
by your channel programs. CA dummy data set may not be opened 
for EXCP.) Some of the procedures performed when OPEN is 
executed are: 


® Reading in the JFCB (job file control block), unless the 
TYPE=J option of the macro instruction was coded 


e Construction of the data extent block (DEB) 


° Transfer of information from the JFCB and data set labels to 


the DCB 
° Verification or creation of standard labels os 
° Tape positioning Ne 


e Loading of your appendage routines 


The parameters of the OPEN macro instruction are: 


[symbol] (dcb address . 
»tCoptions)],...) 


aon FY san o~—_ 


the address of the data control block to be initialized. 
(More than one data control block may be specified.) 





the intended method of I/0 processing of the data set. You 
may specify this parameter as either INPUT, RDBACK, OUTPUT, 
or EXTEND. For magnetic tape, label processing for each of 
these when OPEN is executed is as follows: 


INPUT Header labels are verified. 
RDBACK Trailer labels are verified. 
OUTPUT Header labels are created. 
EXTEND Header labels are created. 


If this parameter is omitted, INPUT is assumed. 
the volume disposition that is to be provided when volume 
switching occurs. The operand values and meanings are as 


follows: 


REREAD Reposition the volume to process the data set 
again. 
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| LEAVE No additional positioning is performed at 
( end-of-volume processing. 


DISP Specifies that a tape volume is to be disposed of 
in the manner implied by the DD statement 
associated with the data set. Direct access volume 
positioning and disposition are not affected by 
this parameter of the OPEN macro instruction. 

There are several dispositions that can be 
specified in the DISP parameter of the DD 
statement: 


DISP=PASS, DELETE, KEEP, CATLG, or UNCATLG. Only 
DISP=PASS has significance at the time an 
end-of-volume condition is encountered. The 
end-of-volume condition may result from the 
issuance of an FEOV macro instruction or may be the 
result of reaching the end of a volume. 


If DISP=PASS was coded in the DD statement, the 
tape will be spaced forward to the logical end of 
the data set on the current volume. 


If a DISP option other than DISP=PASS is coded on 
the DD statement, the action taken when an 
end-of-volume condition occurs depends on (1) how 
many tape units are allocated to the data set and 
€2) how many volumes are specified for the data set 
in the DD statement. This is determined by the 
UNIT= and VOLUME= operands of the DD statement 
associated with the data set. If the number of 
volumes is greater than tne number of units 
allocated, the current volume wiil be rewound and 
unloaded. If the number of volumes is less than or 
equal to the number of units, the current volume is 
( merely rewound. 


If you intend to process a multivolume direct data set, you must 
cause open routines to build a data extent block for each volume 
and issue mount messages for them. This can be done by reading 
in the JFCB with a RDJFCB macro instruction and opening each 
volume of the data set. The following code illustrates the 
procedure: 
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EXECUTING A CHANNEL 


ae DCB1 READS IN THE JFCB 





R3,R3 CLEARS REG 3; IT WILL 
% HOLD COUNT OF VOLS TO 
4 BE OPENED 
Ic R3,JFCBNVOL PUTS # OF VOLS 
x* IN REG 3 
LA R4¢, DCB1 RG POINTS TO DCB FOR 
% VOL TO BE OPENED 
LA R5,1 PUTS SEQUENCE # OF 
¥ FIRST VOL TO BE 
¥ OPENED IN REG 5 
LOOP EQU X* 
STH R5,JFCBVLSQ PUTS SEQ # OF VOL 
¥ TO BE OPENED WHERE 
X OPEN RTNS LOOK. 
OPEN CCRG),O0UTPUT),TYPE=J OPENS ONE VOL 
X NOTE THAT THE TYPE=J OPTION OF THE MACRO MUST BE USED 
LA R4,DCB2-DCB1(R4) INCREMENT REG 4 TO 
* POINT TO THE DCB FOR 
* THE NEXT VOL TO BE 
% OPENED 
LA R5,1¢€R5) INCREMENT TO SEQ # OF 
X% NEXT VOL TO BE OPENED 
BCT R3,LOOP LOOP UNTIL ALL VOLS 
¥% OPEN 
JFCB DS CL176 JFCB READ IN HERE 
ORG JFCB+70 
JFCBVLSQ DS H SEQ # OF VOL TO BE 
* OPENED 
ORG JFCB+117 
JFCBNVOL A FLI1 # OF VOLS IN DATA SET Ye 
% MAPPING MACRO IEFJFCBN MAY ALSO BE USED ey 


DCB1 DCB DDNAME=SYSUT1,MACRF=CE),EXLST=EXITS, DSORG=PS 
DCB2 DCB DDNAME=SYSUT1,MACRF=(CE), EXLST=EXITS, DSORG=P5 
DCB3 DCB DDNAME=SYSUT1,MACRF=CE),EXLST=EXITS, DSORG=PS 
DCB4 DCB DDNAME=SYSUT1,MACRF=CE),EXLST=EXITS, DSORG=PS 
DCB5 DCB DDNAME=SYSUT1,MACRF=CE),EXLST=EXITS, DSORG=PS 
* THIS PROCEDURE WORKS FOR 5 VOLS OR LESS; THE JFCB 

% Bo een ah WHICH IDENTIFIES ADDITIONAL VOLS, CAN'T 
x 


EXITS DS OF 

DC X*87",AL3CJFCB) 87 IDENTIFIES THIS AS 
x THE EXIT LIST ENTRY 
* THAT SHOWS WHERE JFCB 
¥ WILL BE READ IN 


Use of the RDJFCB macro instruction and the OPEN macro 
instruction with the TYPE=J option is explained in detail under 
"Reading and Modifying a Job File Control Block" on page 117. 


PROGRAM CEXCP) 


The EXCP macro instruction requests the initiation of the I/0 
operations of a channel program. You must issue EXCP whenever 
you want to execute one of your channel programs. The format of 
the EXCP macro instruction is: 


a 


the address of the input/output block of the channel 
program to be executed. 
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ASSIGNING AN ALTERNATE TRACK AND COPYING DATA FROM THE DEFECTIVE TRACK CATLAS) 


output and that is APF authorized may, during the execution of 
the program, use the ATLAS macro instruction to obtain an 
alternate track and to copy a defective track onto the alternate 
track. With the use of ATLAS, the program can recover from 
permanent Chard) errors encountered in the execution of the 
following types of I/0 commands: 


e Search ID. 


( A program that uses the EXCP macro instruction for input and 





& Write. (The error condition must be confirmed during the 
execution of the channel program by a CCW that checks the 
data written.) 


e Read count. Errors in the CCHHR part of the count area can 
be recovered from, unless the record is the home address or 
record zero. Errors in the KDD part of the count area 
cannot be recovered from, unless the user has identified the 
defective record. 


Note: ATLAS may be used for all direct access devices with the 
exception of MSS volumes (3330V). 


Your DCB must include the DCBRECFM field, and the field must 
show whether the data set is in the track overflow format. If 
it is, recovery from errors in last records on tracks depends on 
your identifying the track overflow record segments. 


Recovery takes the form of obtaining a good alternate track and 

copying the defective track onto the good alternate one. Unless 

a reexecution of the channel program by ATLAS can correct the 

defect, the user should examine, and if necessary replace, 

defective records in a subsequent job if the data set is to be 
( processed again. 


The format is: 


[symbol] ATLAS PARMADR=faddress} 
[»CHANPRG={R a INR} 1 


[,CNTPTR={P|F}1] 
[ ,WRITS={YES | NO} 1] 





PARMADR 
Address of a parameter address list of the following 
format 


Address of IOB for the channel program that 
encountered the error 


Address of count area field 





The count area field contains the CCHHRKDD of a defective 
record or the CCHH of a track that is to be copied. 
address—A-type address, (2-12), or (1) 


CHANPRG={RINR} 
specifies whether the channel program that encountered the 
error can be executed again. 
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Using ATLAS 





R= Channel program may be executed again by ATLAS. 

7 Before permitting reexecution of the channel program 
by ATLAS, you must reset the error indications of the 
previous execution fields in the DCBIFLGS. (See the 
example of the use of ATLAS below.) 


NR Channel program may not be executed again. 


If this parameter is omitted, R is assumed. 


CNTPTR 
specifies whether the count area field contains a full 
count area CCCHHRKDD) or a partial count area (CCCHH). 


P Part of the count area (the CCHH address of the track 


ta he copied). 


F Full count area CCCHHRKDD count of the record that was 
found defective). 


If this parameter is omitted, P is assumed. 


WRITS 
track overflow segment identification. 


If your data set is in the track overflow format, this 
identification determines recovery from errors in last 
records on tracks. 


VES If this is the last record on the track, it is a 
cnet other than the last of a track overflow 
record. 


NO If this is the last record on the track, it is the 
last or only segment of a track overflow record. 


If this parameter is omitted, it is assumed that it cannot 
be established whether a last record is a segment of an 
overflow record. 


If a channel program encounters a unit check condition Cshown in 
the CSW) in its execution, the EXCP Processor program will 
place the sense bytes in the IOB. ATLAS can be used to recover 
from sense conditions shown by the following bit settings: 


IOBSENSO X'08! Data check 
IOBSENSL X*'80! Permanent 


Also, before using ATLAS, you must reset error indications as 
follows: 


NI DCBIFLGS,X'*3F! Reset the DCBIFLGS error indications. 


The ATLAS program will attempt to find a good alternate track 
and will attempt to copy the defective track onto the good 
track, including all error conditions in either key or data 
areas. The error conditions may be rectified by reexecuting the 
channel program or through the use of the IEHATLAS utility 
program ina subsequent step. 


Example: The following illustrates the use of the ATLAS macro 
instruction. 


62 MVS/XA System-Data Administration 























( EXCP MYIOB 


WAIT ECB=MYECB 

™ MYECB,X'7F* TEST FOR I70 ERROR 

BO NEXT NO, SUCCESSFUL, GO TO 
* ANOTHER ROUTINE 

T™ IOBCSW+3,X*02" UNIT CHECK 

BZ OTHER NO, DO OTHER ERROR 
% PROCESSING 

™ IOBSENSO,X*'08' DATA CHECK 

BNO OTHER NO, CAN'T HANDLE 

™ ITOBSENS1,X'80' PERMANENT 

BNO OTHER NO, CAN'T HANDLE 

NI DCBIFLGS,X*3F'* RESET ERROR 
% INDICATORS 


ATLAS PARMADR=THERE, CHANPRG=R 


Operation of the ATLAS Program 
The ATLAS program (SVC 86): 


e Establishes the availability and address of the next 
alternate track from the format~-4 DSCB of the VTOC. 


e Brings all count fields from the defective track into 
storage to establish the description of the track. 


e Initializes the alternate track. (CWrites the home address 
and record zero.) 


— e Brings the Key and data areas of each record into storage, 
y one at a time, and combines them with their new count area 
to write the complete record onto the alternate track. 


® When the copying is finished, chains the alternate to the 
defective track and updates the VTOC. 


Control is returned to your program at the next executable 
instruction following the ATLAS macro instruction. 


Return Codes from the ATLAS Program 


The success of the ATLAS macro instruction can be determined by 
examining the contents of register 15, which will contain one of 
the return codes described below. If register 15 contains 
decimal 0, 36, 40, or 44, the contents of register 0 may be 
Significant. 
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Code 
O0CX*00') 


40X04") 
ROX'0R") 
12¢X'0C") 


L6CX'10') 


200X'14") 


240X'18') 


28CX*1C*) 


S20X'20') 


36 0X*24") 


G0CX"28") 








Meaning 


Successful completion. Key and data areas have been 
copied from the defective track onto a good 
alternate one. The only error encountered was in 


the record identified by the user's CCHHRKDD value. 


If the channel program is reexecutable, it has been 
successfully reexecuted. 


This device type does not have alternate tracks that 
can be assigned by programming. 


lave peen 


A request for storage (GETMAIN macro instruction) 
could not be satisfied. 


All attempts to initialize and transfer data to an 

alternate track failed. The number of attempts made 
a equal to 10% of the assigned alternates for the 
evice. | 


The type of error shown by the sense byte cannot be 
handled through the use of the ATLAS macro 
instruction. The condition is other than a data 
check Cin the count or data areas) or a missing 
address marker. 


The format-4 DSCB of the VTOQC cannot be read; 
therefore alternate track information is not 
available to ATLAS. 


The record specified by the user was the format-4 
DSCB, and it could not be read. 


An error found in count area of last record on the 
track cannot be handled because last-record-on-track 
identification is not supplied. 


An error was encountered when reading or writing the 
home address record or record zero. No error 
recovery has taken place. 


If register 0 contains X'0O1 00 00 00°, the defect is 
in record zero. 


Successful completion. Key and data areas have been 
copied from the defective track onto a good 

alternate one. However, the alternate track may have 
records with defective key or data areas. Register 0 
hae erg the first three found defective as 
ollows: 


nRRR 


n——The number of record numbers that follow (0, Il, 


2, or 3). 


R—The hexadecimal number of the record found 
defective but copied anyway. 


If the channel program is reexecutable, it has been 
successfully reexecuted. 
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END OF VOLUME (EOV) 





Code Meaning 


GG4CX'2C') Errors encountered and no alternate track has been 
assigned. The return parameter register Cregister 0) 
will contain the R of a maximum of three error 
records. 


Error conditions that return this code are: 


1. ATLAS received an error indication for a record 
with a data length in the count field of zero. 
Recovery was not possible because a distinction 
cannot be made between an EOF record and an 
invalid data length. 


2. An error occurred while reading the count field 
of a record, and the KDD Ckey length-data 
length) was found to be defective. 


3. More than three records on the specified track 
contained errors in their count fields. 


48(30) No errors found on the track, no alternate assigned. 
ATLAS will not assign an alternate unless a track 
has at least one defective record. 


520349) I/O error in reexecuting user's channel program. A 
good alternate is chained to the defective track, 
and data has been transferred. The user's control 
blocks will give indication of the error condition 
causing failure in reexecution of the channel 
program. 


56(38) The DCB reflects a track overflow data set, but the 
UCB device type shows that the device does not 
support track overflow. 


60CX*3C") The CCHH of the user-specified count area is not 
within the extents of the data set. 


64CX*G0") The device is an MSS virtual device, which is not 
supported. 


The EOV macro instruction identifies end-of-volume and 
end-of-data-set conditions. For an end-of-volume condition, EQOV 
causes switching of volumes and verification or creation of 
standard labels. For an end-of-data-set condition, EOV causes 
your end-of-data set routine to be entered. Before processing 
trailer labels on a tape input data set, you must decrement the 
DCBBLKCT field. You issue EOV if switching of magnetic tape or 
direct access volumes is necessary, or if secondary allocation 
eee aia performed for a direct access data set opened for 
output. 


For magnetic tape, you must issue EOV when either a tapemark is 
read or a reflective spot is written over. In these cases, bit 
settings in the l-byte DCBOFLGS field of the data control block 
determine the action to be taken when EOV is executed. Before 
issuing EOV for magnetic tape, you must make sure that 
appropriate bits are set in DCBOFLGS. Bit positions 2, 3, 6, 
and 7 of DCBOFLGS are used only by the system; you are concerned 
with bit positions 0, 1, 4, and 5. The use of these DCBOFLGS 
bit positions is as follows: 
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Bit 0 





set to 1 indicates that a write command was executed and — 
that a tapemark is to be written. c* 





Bit 1 : | "2 4 
indicates that a backward read was the last I/0 operation. 

Bit 4 | 
indicates that data sets of unlike attributes are to be 
concatenated. 

Bit 5 


indicates that a tapemark has been read. 


If bits 0 and 5 of DCBOFLGS are both off when EOV is executed, 
tne tape is spaced past a tapemark, and standard labels, if 
present, are verified on both the old and new volumes. The 
direction of spacing depends on bit 1. If bit 1 is off, the ! 
tape is spaced forward; if bit 1 is on, the tape is sackspaced. 


If bit 0 is on, but bit 5 is off, when EOV is executed, a 
tapemark is written immediately following the last data record 
of the data set. Standard labels, if specified, are created on 
the old and the new volume. 


After issuing EOV for sequentially organized output data sets on 
direct access volumes, you can determine whether additional 
space was obtained on the same or a different volume. You do 
this by examining the data extent block CDEB) and the unit 
control block CUCB). If neither the address of the UCB, as 
shown in the DEB, nor the volume serial number, as shown in the 
UCB, has changed, additional space was obtained on the same 
volume. Otherwise, space was obtained on a different volume. 


The only parameter of the EOV macro instruction is: 
eS 


, | : 


the address oF the data Pentre! block that is opened for 


the data set. If this parameter is specified as (1), 
register 1 must contain this address. 


Note: To learn how the system disposes of a tape volume when an 
EOV macro is issued, see the description of the DISP parameter 
under "Initializing Data Control Blocks COPEN)®" on page 58 


RESTORING DATA CONTROL BLOCKS (CLOSE) 


The CLOSE macro instruction restores one or more data control 
blocks so that processing of their associated data sets can be 
terminated. You must issue CLOSE for all data control blocks 
that were used by your channel programs. Some of the procedures 
performed when CLOSE is executed are: 


e Release of data extent block (DEB) 


e Removal of information transferred to data control block 
fields when OPEN was executed 


e Verification or creation of standard labels 

e Volume disposition 

e Release of programmer-written appendage routines 

When CLOSE is issued for data sets on magnetic tape volumes, 
labels are processed according to bit settings in the DCBOFLGS 


field of the data control block. Before issuing CLOSE for 
magnetic tape, you must set the appropriate bits in DCBOFLGS. 
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The DCBOFLGS bit positions that you are concerned with are 
listed in the EOV macro instruction description. 


For information about the forms of the CLOSE macro and their 
pee er ee see 3 


CONTROL BLOCK FIELDS 


The fields of the input/output block, event control block, and 
data extent block are illustrated and explained here; the data 
control block fields are described with the parameters of the 
DCB macro instruction under "EXCP Requirements" on page 39. 


INPUT/OUTPUT BLOCK (IOB) FIELDS 


The input/output block CIOB) is not automatically constructed by 
a macro instruction; it must be defined as a series of constants 
and must be ona fullword boundary. For unit-record and tape 
devices, the IOB is 32 bytes in length. For direct access, 
teleprocessing, and graphic devices, 8 additional bytes must be 
provided. You may want to use the system mapping macro IEZIOB, 
which expands into a DSECT, to help in constructing an IOB. 


In Figure 14 the diagonally-~ruled areas indicate fields in which 
you must specify information. The other fields are used by the 
system and must be defined as all zeros. You may not place 
information into these fields, but you may examine them. 


IOBFLAG1 (1 byte) 
You must set bit positions 0, 1, and 6. OQne-bits in 
positions 0 and 1 indicate data chaining and command 
chaining, respectively. (CIf both data chaining and command 
chaining are specified, the system does not use error 
recovery routines except for the direct access devices.) A 
one-bit in position 6 indicates that the channel program is 
not a "related" request; that is, the channel program is 
not related to any other channel program. If you intend to 
issue an EXCP macro with a BSAM, QSAM, or BPAM data control 

block, you may want to turn on bit 7 to prevent 

access~method appendages from processing the I/O request. 


IOBFLAG2 (1 byte) 
If you set bit 6 in the IOBFLAGI] field to zero, bits 2 and 
3 in this field must then be set to: 


e 00, if any channel program or appendage associated with 
a related request might modify this IQB or channel 
program. 


e 01, if the conditions requiring a 00 setting don't 
apply, but the CHE or ABE appendage might retry this 
channel program if it completes normally or with the 
aoe exception or wrong iength- record bits on in the 


e 10 in all other cases. 


The three combinations of bits 2 and 3 represent the three 
kinds of related requests, known as type 1 (00), type 2 
C01), and type 3 €10). The type you use determines how 
much the EXCP Processor can overlap the processing of 
related requests. Type 3 allows the greatest overlap, 
normally making it possible to quickly reuse a device after 
a channel-end interruption. (Related requests that were — 
executed on a pre-MVS system are executed as type-l 
requests if not modified.) 


IOBSENSO and IOBSENSI (C2 bytes) 
are placed into the input/output block by the EXCP 
Processor when a unit check occurs. On occasion, the 
system is unable to obtain any sense bytes because of unit 
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IOBECBCC SAAT SS AAS AS TOBECBPT SASSAS7A7S/7077 
ee 


0C0)/ / 
4/////\TOBFLAGI IZ : 
4/4447 / 
(4) hhh | 
IOBFLAGS 


IOBCSW 





> All 










16¢€10) SAO ASAAAAAAAAAAAA AAA AA AAA AAAS AAA AA 
SAAS SSSA TOBSTART 444777770871 777 


he ee ee 









IOBSIOCC 














SULOOLODAOTOAAOOOAAAAAAAAAAAAANAAAA AA 
SOSA SAAC TOBDCBPT 4/4/7707 7/71867/7 
SOSSAAAAAAAA AAA AA AAA AA AAA AAA AAA A AAA A A A 


Devices 

IOBRESTR+1 
2801C) SSASSSSSSSAASAAAAAA AAA ASA 
S4444444444f TOBINCAM S/477/7/7/7/7/7 IOBERRCT 
SAISON AAA AAA ALAA AAAS AA 


32020) SSSS/4 1416017 
1/17 IOBSEEK //7 
/ (first byte, M) 


20014) 





Reserved 
















624018) 
IOBRESTR 













— 
> Direct Access, Teleprocessing, and 
= Graphic Devices | ee 









S3C21) SSSSSSLSSSSASASSASSASAA AAS AAS 
le ee 


Direct 
VISAS ASA AA ALAA AAS A AAA AAA AAS AAA AA SAAS | Access 






Sf 7 IOBSEEK S110 > Storage 
SASS SSS Csecond through eighth bytes, //// Devices 
SASSO AAAAAASA AAA AAAS BBCCHHR) VM A CDASD) 


SASSO AAA AAA AAS AAS AAA A AAA 39C2!T) 


Figure 14. Input/Output Block CIOB) Format 


checks when sense commands are issued. In this case, the 
system simulates sense bytes by moving X'lLOFE!' to IJOBSENSO 
and IOBSENS1. 


IOBECBCC (1 byte) 
the first byte of the completion code for the channel 
program. The system places this code in the high-order 
byte of the event control block when the channel program is 
posted complete. The completion codes and their meanings 
are a under "Event Control Block CECB) Fields™ on 
page . 


IOBECBPT (C3 bytes) 
the address of the 4-byte event control block you have 
provided. 


IOBFLAG3 (1 byte) 
is used only by the system. 
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EVENT CONTROL BLOCK 


IOBCSW (€7 bytes) 
the low-order seven bytes of the channel status word that 
are placed into this field each time a channel-end or PCI 
interruption occurs. 


IOBSIOCC (1 byte) 
in bits 0 and 1, the instruction-length code; in bits 2 and 
3, the start subchannel (CSSCH) condition code for the 
instruction the system issues to start the channel program; 
and, in bits 4% through 7, the program mask. 


IOBSTART (3 bytes) 
the starting address of the channel program to be executed. 


Reserved (1 byte) 
used only by the system. 


IOBDCBPT (3 bytes) 
the address of the data control block of the data set to be 
read or written by the channel program. 


IOBRESTR C1 byte) 
used by the system for volume repositioning in error 
recovery procedures. 


IOBRESTR+t1 (€3 bytes) 
if a related channel program is permanently in error, used 
by the system to chain together IOBs that represent 
dependent channel programs. To learn more about the 
conditions under which the chain is built, see 
ae Handling and Error Recovery Procedures™ on 
page 


IOBINCAM (2 bytes) 

for magnetic tape, the amount by which the block count. 
CDCBBLKCT) field in the device-~dependent portion of the 
data control block is to be incremented. You may alter 
these bytes at any time. For forward operations, these 
bytes should contain a binary positive integer Cusually 
+1); for backward operations, they should contain a binary 
negative integer. When these bytes are not used, all zeros 
must be specified. 


Reserved (2 bytes) 
used only by the system. 


IOBSEEK (first byte, M) 
for direct access devices, the extent entry in the data 
extent block that is associated with the channel program (0 
indicates the first entry; 1 indicates the second, and so 
forth). For teleprocessing and graphic devices, it 
contains the UCB index. 


IOBSEEK Clast 7 bytes, BBCCHHR) 


for direct access devices, the seek address for your 
channel program. 


(ECB) FIELDS 


You must define an event control block CECB) as a 4-byte area on 
a fullword boundary. When the channel program has been 


completed, the input/output supervisor places a completion code 


containing status information into the ECB (Figure 15 on 
page 70). Before examining this information, you must test for 
the setting of the "complete bit." If the complete bit is not 
on, and your problem program cannot perform other useful 
operations, you should issue a WAIT macro instruction that 
specifies the event control block. Under no circumstances 
es you construct a program loop that tests for the complete 
si oa | 
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WATT bit=0 COMPLETE bit=1 Remainder of completion code 





bit : : 3 3 | 
0 1 | | 2 31 
Wait bit | | 


A one bit in this position indicates that the WAIT macro instruction has been 
issued, but the channel program has not been completed. 


Complete bit 


Loa Lis 
mn ons wait ii uit 


i Sition indicates that the channel program has been 
completed; if it h 


OSi 
s not been completed, a zero bit is in this position. 


Completion code 
This code, which includes the wait and complete bits, may be one of the 
following 4G-byte hexadecimal expressions: 


Code Meaning 
7FO000000 The channel program has terminated without error. 
41000000 The channel program has terminated with a permanent error. 


42000000 The channel program has terminated because a direct access extent 
address has been violated. 


44000000 The channel program has been intercepted because of a permanent error 
associated with a device end for the previous request. You may 
reissue the EXCP macro instruction to restart the channel program. 


48000000 The request queue element for a channel program has been made 
available after it has been purged. 


G4B000000 One of the following errors occurred during error recovery processing 
for a tape device. 


@ The CSW command address in the IOB is zeros. 
6 An unexpected load point was encountered. 


GFO0Q00000 Error recovery routines have been entered because of direct access 
error but are unable to read the home address or record 0 


Figure 15. Event Control Block CECB) after Posting of Completion Code CEXCP) 


DATA EXTENT BLOCK (DEB) FIELDS 


The data extent block CDEB) is constructed by the system when an 

OPEN macro instruction is issued for the data control block. 

You may not modify the fields of the DEB, but you may examine 
them. _The DEB format and field descriptions are contained in 


» » 
ay Ah. iN 


The EXCPVR macro instruction provides you with the same 
functions as the EXCP macro instruction (that is, a 
device-dependent means of performing input/output operations). 

In addition, it allows your program to improve the efficiency of 
the I/0 operations in a paging environment by translating its 
own virtual channel programs to real channel programs. 
Authorized programs are allowed to execute ina V=V area and 
provide the EXCP processor with real channel programs. This 
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ae, 























eliminates the translation of channel programs by the EXCP 
processor. The program issuing the EXCPVR must remain in 
authorized state until the completion of the channel programs. 


Problem programs are authorized to use the EXCPVR macro 
instruction under the authorized program facility CAPF). A 
description of how to authorize a program can be found in 


fe) 
the address of the input/output block of the channel 
program to be executed. 


To use EXCPVR, you must do all the things you would do to 
execute an EXCP request; in addition you must: 


1. Code PGFX=YES in the DCB associated with the EXCPVR requests 
and provide a page-fix (PGFX) appendage by specifying 
SIOA=symbol in the DCB 


2. Fix the data area that contains your channel program, the 
data areas that are referred to by your channel program, 
your PCI appendage (if your program can generate 
program-controlled interrupts), and any area referred to by 
your PCI appendage. To cause EXCP to fix these data areas, 
you build a list that contains the addresses of these 
virtual areas. You should build the list in your PGFX 
appendage. 


3. Determine whether the data areas in virtual storage 
specified in the address fields of your CCWs cross page 
boundaries. If they do, you must build an indirect data 
address list CIDAL) and put the address of the IDAL in the 
affected CCW. 


G4. Translate the addresses in your CCWs from virtual to real 
addresses. 


All other areas related to the EXCP/EXCPVR I/0 operation Cthat 
is, CCWs, IDAWs, IOBs, DEBs, DCBs, appendages, and so forth) 
must remain 24-bit addressable. Note, however, that the EXCP 
processor will allow both 24-bit and 31-bit virtual I/0 buffers 
to be fixed above 16 megabytes real. 


Items 3 and 4 must be done in your start-I/0 (SIO) appendage. A 
haat Ae of the SIO appendage is presented under "Appendages" 
on page : 


BUILDING THE LIST OF DATA AREAS TO BE FIXED 


The EXCP processor expects programs using the EXCPVR macro 
instruction to pass a list of data areas to be fixed. This list 
1s to be built in the PGFX appendage, as described below. 


The data areas you must fix in real storage (if not already 
fixed in real storage) are: 


Ll. The channel program. If the channel program is already ina 
fixed subpool, it does not have to be fixed. 


2. The data areas to which your channel program will be writing 
and from which your channel program will be reading. If the 
data areas are already ina fixed subpool, they do not have 
to be fixed. 


3. The PCI appendage, if used, and any areas referred to in the 
PCI appendage. 


4. Any system or user control blocks Cand the DEB). 
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PAGE FIX (PGFX) AND 











You need not fix areas that have already been fixed, such as the 
modules that reside in the fixed link pack area C(LPA). 


EXCPVR users can specify 31-bit real data areas by creating CCWs 
through the use of IDANWs. 


START-I/0 (SIO) APPENDAGE 


This appendage comprises two essentially independent appendages. 
The complete appendage can be viewed as a re-enterable 
subroutine having two entry points, one for the SIO appendage 
and one for the PGFX appendage. 


The SIO entry point is located a offset 0 in the subroutine; 


any other location in the appendage may be branched to from this 


entry point. The entry point of the PGFX appendage is at offset 
+4 in the SIO subroutine, which is set in register 15 as the 
entry point of the PGFX appendage. 


Page Fix (PGFX) Appendage: The purpose of this appendage is to 
list all the areas that must be fixed to prevent paging 
exceptions during the execution of the current I/0 request. 
This appendage may be entered more than once. However, each 
time it is entered, it must create the same list of areas to be 
fixed. The appendage may use the 16-word save area pointed to 
by register 13. Registers 10, 11, and 13 may be used as work 
registers. 


Page-Fix List Processing 


Each page-fix entry placed in the list by the appendage must 
have the following doubleword format: 


‘Joy. 31132133 63| 





Starting virtual Ending virtual 
address of area address of area 
to be fixed to be fixed + l 





On return from your PGFX appendage to the EXCP processor (via 
the return address provided in register 14), register 10 must 
point to the first page-fix entry and register 11 must contain 
the number of page-fix entries in the work area. The EXCP 
processor then fixes the pages corresponding to the areas listed 
by the PGFX appendage. The pages remain fixed until the 
associated I/0 request terminates. 


If either the channel end appendage or the abnormal end 
appendage returns via the return address in register 14 plus 8, 
the PGFX appendage is not normally reentered. Instead, the SIO 
appendage is entered, and the page-~fix list built by the PGFX 
appendage is still active. However, the PGFX appendage is 
entered after either the channel end appendage or the abnormal 
end appendage returns via the return address in register 14 plus 
8 when a PURGE macro has been issued (for instance, when a 
storage swap has occurred). In this case, when I/0 is restored, 
the PGFX appendage is entered. 


Note: The page-fix list must be in page-~fixed storage. 
SIO APPENDAGE: If you are using EXCPVR to execute your channel 


program, you must translate the virtual addresses in the 
operands of your channel program to real addresses. This should 


be done in your SIO appendage. If indirect data addressing is 


required, the SIO appendage should also build the indirect data 
address lists CIDALs). and turn on the IDA indicators in the 
associated CCWs. 
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Translating Virtual Addresses and Building the IDAL: You must 
convert the virtual addresses in the channel program to real 
addresses. You must also check the areas whose addresses appear 
in bits 8 through 3l of your CCWs to determine whether the data 
areas cross 2K-byte boundaries. If they do, you must provide an 
entry in the IDAL for each 2K-byte boundary crossed. The 
channel subsystem uses the IDAL to identify the address where it 
will continue reading or writing when a 2K-byte boundary is 
crossed during a read or write operation. The IDAL must contain 
real addresses when it is processed by the channel. 


In MVS/XA, the LRA instruction returns a 3l]l-bit real address 
regardless of the addressing mode. You must be careful when you 
construct the IDAW to ensure that the real storage obtained by 
GETMAIN Cor branch entry) is below 16 megabytes. Do your page 
fixing before you issue the LRA. (See erviso 1 

fe) or for 
— on how to obtain =e storage below 16 megabytes 
rea 


Command Address of the SASS Byte 
Code IDAL aM he Count 

31 32 39 40 G7 48 
IDAL 

> 





First Indirect Data 
Address Word 


Second Indirect Data 


Address Word 


Subsequent Indirect 
Data Address Word 





Notes: 


1. You must put one entry in the IDAL for each 2K-byte page 
boundary your data area crosses. 


2. If the CCW has an IDAL address rather than a data address, 
bit 37 must be set to signal this to the channel. 


3. The maximum number of entries needed in the IDAL is 
determined from the count in the CCW as follows: 


Number of IDAL entries=CCCCW byte-count — 1)/2048) + 1. 
CRound Er oeyeesen to next highest integer if remainder is 
not zero. 


The number of IDAL entries required ultimately depends on the 
number of 2K-byte boundaries crossed by the data. For example, 
if your data is 800 bytes long and does not cross a 2K-byte page 
boundary, no IDAL entries are required. If your data crosses a 
GK-byte page boundary, then two IDAL entries are required. If 
your data is 5000 bytes long, at least two IDAL entries are 
required. If your data crosses two 4K-byte page boundaries, 
four IDAL entries are required. 


The first indirect address is the real address of the first byte 
of the data area. The second and subsequent indirect addresses 
are the real addresses of the second and subsequent 2K-byte 
boundaries of the data area. 
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For example, if the data area real address is X'70/7FF* and the 
byte count is X'1802', the IDAL would contain the following real 


addresses Cassuming the real addresses are contiguous, which may Gos 
not always be the case): | 
WS 
TO7FF 
70800 
71000 | 


If the data area real address is X'707FF* and the byte count is 
X*800", the IDAL would contain the following addresses: 


707FF 
70800 


/ 
\ 


a 
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Execute direct access program (XDAP) is a macro instruction that 
you may use to read, verify, or update a block ona direct 
access volume. This chapter explains what the XDAP macro 
instruction does and how you can use it. The control block 
generated when XDAP is issued and the macro instructions used 
with XDAP are also discussed. 


Because most of the specifications for XDAP are similar to those 
for the execute channel program CEXCP) macro instruction, you 
should be familiar with the "Executing Your Own Channel Programs 
CEXCP)" chapter of this publication, and with the information 
contained in Data Administration Guide that provides how-to 
information for using the access method routines of the system 
control program. 


If you are not using the standard IBM data access methods, you 
can, by issuing XDAP, generate the control information and 
channel program necessary for reading or updating the records of 
a data set. (However, XDAP cannot be used to read, verify, or 
update a SYSIN or SYSOUT data set.) | 


You cannot use XDAP to add blocks to a data set, but you can use 
it to change the keys of existing blocks. Any block 

eoteee rae and any data set organization can be read or 
updated. 


Although the use of XDAP requires less storage than do the 
standard access methods, it does not provide many of the control 
program services that are included in the access methods. For 
example, when XDAP is issued, the system does not BLOCK or 
unblock records and does not verify block length. 


To issue XDAP, you must provide the actual track address af the 
track containing the block to be processed. You must also 
provide either the block identification or the Key of the block, 
and specify which of these is to be used to locate the block. 

If a block is located by identification, both the key and data 
portions of the block may be read or updated. If a block is 
located by Key, only the data portion can be processed. 


For additional control over I/0 operations, you may write 
appendages that must be entered into the LPA library. 
Descriptions of these routines and their coding specifications 
are included under Chapter 2, "Executing Your Own Channel — 
Programs CEXCP)"™ on page 36 


When using the XDAP macro instruction, you must, somewhere in 
your program, code a DCB macro instruction that produces a data 
control block (DCB) for the data set to be read or updated. You 
must also code an OPEN macro instruction that initializes the 
data control block and produces a data extent block (DEB). The 
OPEN macro instruction must be executed before any XDAP macro 
instructions are executed. 
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When the XDAP macro instruction is assembled, a control block | 
and executable code are generated. This control block may be 
logically divided into three sections: 


e An auenk control block CECB) that is supplied with a 
completion code each time the direct access channel program 
is terminated. | 


e An input/output block CIOB) that contains information about 
the direct access channel program. 


6 A direct access channel program that consists of three or 
four channel command words (CCWs). The type of channel 
program generated depends on specifications in the 


parameters of the XDAP macro pita aeerts Peas executed, it 


reads, updates: or verifies “the block. 


When the channel program has terminated, a completion code is 
placed into the event control block. After issuing XDAP, you 
should therefore issue a WAIT macro instruction, specifying the 
address of the event control block, to regain control when the 
direct access program has terminated. If volume switching is 
necessary, you must issue an EOV macro instruction. When 
processing of the data set has been completed, you must issue a 
CLOSE macro instruction to restore the data control block. 





When you are using the XDAP macro instruction, you must also 
code DCB, OPEN, CLOSE, WAIT, and, in some cases, the EQV macro 
instructions. The parameters of the XDAP macro instruction are 
listed and described here. For the other required macro 
instructions, special requirements or options are explained, but 
you should see "Macro Specifications for Use with EXCP™ on 

page 51 for listings of their parameters. 


DEFINING A DATA CONTROL BLOCK (DCB) 


You must issue a DCB macro instruction for each data set to be 
read, updated, or verified by the direct access channel program. 
To learn which macro instruction parameters to code, see 
"Defining Data Control Blocks for EXCP CDCB)™ on page 51. 


INITIALIZING A DATA CONTROL BLOCK (OPEN) 


The OPEN macro instruction initializes one or more data control 

blocks so that their associated data sets can be processed. You 
must issue OPEN for all data control blocks that are to be used 

by the direct access program. Some of the procedures performed 

when OPEN is executed are: 


© Construction of data extent block (DEB) 


® Transfer of information from DD statements and data set 
labels to the data control block 


e Verification or creation of standard labels 

e Loading of programmer-written appendage routines 

The two parameters of the OPEN macro instruction are the 
address(es) of the data control block(€s) to be initialized and 
the intended method of I“0 processing of the data set. 


e 
method of processing may be specified as INPUT, OUTPUT, EXTEND; 
however, if nothing is specified, INPUT is assumed. 
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| EXECUTING DIRECT ACCESS PROGRAMS (XDAP) 


The XDAP macro instruction produces the XDAP control block Cthat 
is, the ECB, IOB, and channel program) and executes the direct 
access channel program. The format of the XDAP macro 
instruction is: 


»lLength-value 
5) [ (key-a ddr 2 keyvleng th-value ) ] 


blkref-addr 
> tgector-addr] 
[,>MF={E|L}] 





the symbolic name to be assigned to the XDAP event control 
block. Registers can be used only with MF=E. 


type——{IRI|RKIWIIWKIVIIVK} 
the type of I/0 operation intended for the data set and the 
method by which blocks of the data set are to be located. 
One of the combinations shown must be coded in this field. 


The codes and their meanings are: 
R Read a block. 
W Update a block. 


V Verify that the device is able to read the contents of 
a block, but do not transfer data. 


I Locate a block by identification. (The Key portion, if 
present, and the data portion of the block are read, 
updated, or verified.) 


K Locate a block by key. (COnly the data portion of the 
block is read, updated, or verified.) If you code this 
value, you must code the ‘'kKey~addr,keylength-value’ 
operands. 


as d e - 
the address of the data control block for the data set. If 
this data control block is also being used by a sequential 
access method CBSAM, BPAM, QSAM), you must reassemble the 
XDAP macro instruction. Otherwise, sequential access 
method appendages will be called at the conclusion of the 
XDAP channel program... 


fia mn ] r = 
the address of an input or output area for a block of the 
data set. 


the number of bytes to be transferred to or from the input 
or output area. If blocks are to be located by 
identification and the data set contains keys, the value 
must include the length of the key. The maximum number of 
bytes transferred is 32767. 


when blocks are to be located by key, the address of a 


virtual storage field that contains the key of the block to 
be read, updated, or verified. 


when blocks are to be located by key, the length of the 
key. The maximum length is 255 bytes. 
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the address of a field in virtual storage containing the 
actual track address of the track containing the block to 
be located. The actual address of a block is in the form 
MBBCCHHR, where M indicates which extent entry in the data 
extent block is associated with the direct access program; 
BB is not used, but must be zero; CC indicates the cylinder 
address; HH indicates the actual track address; and R 
indicates the block identification. R is not used when 
blocks are to be located by key. (For more detailed 
information, see "Converting a Relative Track Address to an 
Actual Track Address" on page 80.) 





the address of a 1- byte field containing a sector value. 


a re eee 
The sector-address parameter is used for rotatisnal 


position sensing (RPS) devices only. The parameter is 
optional, but its use will improve channel performance. 
When the parameter is coded, a set-sector CCW Cusing the 
sector value indicated by the data address field) precedes 
the search-ID-equal command in the channel program. The 
sector-address parameter is ignored if the type parameter 
is coded as RK, WK, or VK. If a sector address is 
specified in the execute form of the macro, then a sector 
address, not necessarily the same, must be specified in the 
ag ae The sector address in the executable form will 
e used. 


Note: No validity check is made on either the address or 
the sector value when the XDAP macro is issued. However, a 
unit check/command reject interruption will occur during 
channel~program execution if the sector value is invalid 
for the device or if the sector-addr operand is used when 
accessing a device without RPS. (For more detailed 
information, see "Obtaining Sector Number of a Block ona 
Device with the RPS Feature™ on page 82.) 


MF /- 
— 5 ‘ \ f 
you may use the L-form of the XDAP macro instruction for a Tee 
macro expansion consisting of only a parameter list, or the 
E-form for a macro expansion consisting of only executable 
instructions. 
MF=E 
The first operand Cecb-symbol) is required and may be coded 
as a symbol or supplied in registers 2 through 12. The 
type, dcb-addr, area-addr, and length-value operands may be 
‘supplied in either the L- or E-form. The blkref-addr 
operand may be supplied in the E-form or moved into the 
IOBSEEK field of the IOB by you. The sector-addr is 
optional; it may be coded either in both the L- and E-form 
or in neither. 
MF=L 


The first two operands Cecb-symbol and type) are required 
and must be coded as symbols. If you choose to code 
length-value or keylength-value, they must be absolute 
expressions. Other operands, if coded, must be A-type 
addresses. (Cblkref-addr is ignored if coded. ) 


Note: The XDAP macro builds a channel program containing A-type 
addresses. These addresses refer to storage within the L-form 
of the macro. If you copy the L-form of the macro to a workarea 
so that the program may be reentrant, the E-form of the XDAP 
macro does not update the A-type addresses. This results in an 
invalid channel program. 


The deb-addr, area~addr, blkref-addr, and sector-value operands 
may be coded as RX-type addresses or supplied in registers 2 
through 12. The length-value and keylength-value operands can 
be specified as absolute expressions or decimal integers or 
supplied in registers 2 through 12. 
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END OF VOLUME (EOV) 








The EOV macro instruction identifies end-of-volume and 
end-of-data-set conditions. For an end-of-volume condition, EQOV 
causes switching of volumes and verification or creation of 
standard labels. For an end~-of-data-set condition, EOV causes 
your end-of-data-~set routine to be entered. When using XDAP, 
you issue EOV if switching of direct access volumes 18S necessary 
or if secondary allocation is to be performed for a direct 
access data set opened for output. 


The only parameter of the EQV macro instruction is the address 
of the data control block of the data set. 


RESTORING A DATA CONTROL BLOCK (CLOSE) 


EVENT CONTROL BLOCK 


Chapter 


The CLOSE macro instruction restores one or more data control 
blocks so that processing of their associated data sets can be 
terminated. You must issue CLOSE for all data sets that were 
used by the direct access channel program. Some of the 
procedures performed when CLOSE is executed are: 


® Release of data extent block (DEB) 


e Removal of information transferred to data control block 
fields when OPEN was executed 


@ Verification or creation of standard labels 

® Release of programmer-written appendage routines 

The CLOSE macro instruction must identify the address of at 
least one data control block to be restored, and may specify 


other options. To learn what these options are and how they are 
specified, see Data Adminis ation: Macro Instruction Reference. 





The three control blocks generated during execution of the XDAP 
macro instruction are described here. 


CECB) 


The event control block CECB) begins on a fullword boundary and 
occupies the first 4 bytes of the XDAP control block. Each time 
the direct access channel program terminates, the I/O supervisor 
places a completion code containing status information into the 
event control block (Figure 16 on page 80). Before examining 
this information, you must wait for the completion of the 
channel program by issuing a WAIT macro instruction that 
specifies the address of the event control block. 


INPUT/OUTPUT BLOCK (IOB) 


The input/output block CIOB) is 40 bytes in length and 
immediately follows the event control block. "Control Block 
Fields" on page 67 contains a diagram of the input/output block 
(Figure 16 on page 80). You may want to examine the IOBSENSO, 
IOBSENS1, and IOBCSW fields if the ECB is posted with X'41'. 
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ar 
bit 
0 1] 2 31 
Wait bit 
A one bit in this position indicates that the direct access channel program has 
not been completed. 
Complete bit 
A scone bit in this position indicates that the channel program has deen 
completed; if it has not been completed, a zero bit is in this position. 
Completion code | 
This code, including the wait and complete bits, may be one of the following 
G-byte hexadecimal expressions: 
Code Meaning 
7FO000000 Direct access program has terminated without error. 
41000000 Direct access program has terminated with permanent error. 
42000000 Direct access program has terminated because a direct access extent 
address has been violated. 
GFO00Q00000 Error recovery routines have been entered because of direct access 
error but are unable to read home address or record 0 
Figure 16. Event Control Block CECB) after Posting of Completion Code CXDAP) 
@ 
jw 











DIRECT ACCESS CHANNEL PROGRAM 


De 


The direct access channel program is 24 bytes in length Cexcept 
when set sector is used for RPS devices) and immediately follows 
the input/output block. Depending on the type of I/0 operation 
specified in the XDAP macro instruction, one of four channel 
programs may be generated. The three channel command words for 
each of the four possible channel programs are shown in 

Figure 17 on page 8l 


When a sector address is specified with an RI, VI, or WI 
operation, the channel program is 32 bytes in length. Each of 
these channel programs in Figure 17 on page 81 would be, in this 
case, preceded by a set sector command. 


Pe A fi » wh ‘ ° 
rw EY PA 17 4 Es ‘ alk mi” mi" alm A 342954 


To issue XDAP, you must provide the actual track address of the 
track containing the block to be processed. If you know only 
the relative track address, you can convert it to the actual 
address by using a resident system routine. The entry point to 
this conversion routine is labeled IECPCNVT. The address of the 
entry point (CCVTPCNVT) is in the communication vector table 
CCVT). The address of the CVT is in location 16. (For the 
displacements and descriptions of the CVT fields, see Debugging 
Handbook. ) 
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Type of I/0 Operation CCW Command Code 


Read by identification 
Verify by identification? 
Read by key 

Verify by key} 


Write by identification 


Write by Key 


Search ID Equal 
Transfer in Channel 
Read Key and Data 


Search Key Equal 
Transfer in Channel 
Read Data 


Search ID Equal 
Transfer in Channel 
Write Key and Data 


Search Key Equal 
Transfer in Channel 
Write Data 


NN&M WNM WHR WHE 


1 For verifying operations, the third CCW is flagged to 
suppress the transfer of information to virtual storage. 


Figure 17. 


The XDAP Channel Programs 


The conversion routine does all its work in general registers. 
You must load registers 0, 1, 2, 14, and 15 with input to the 


routine. 
Register 
0 


5-8 
9-15 


14 


15 


Register usage is as follows: 
Use 


Must be loaded with a 4-byte value of the form TTRN, 
where TT is the track number relative to the beginning 
of the data set, R is the the block identification on 
that track, and N is the concatenation number of a 
BPAM data set. (¢€0 indicates the first data set in the 
concatenation, an nonconcatenated BPAM data set, or a 
non-BPAM data set.) 


Must be loaded with the address of the data extent 
block (DEB) of the data set. 


Must be loaded with the address of an 8~-byte area that 
1s to receive the actual address of the block to be 
processed. The converted address is of the form 
MBBCCHKR, where M indicates which extent entry in the 
data extent block is associated with the direct access 
program (0 indicates the first extent, 1 indicates the 
second, and so forth); BB is two bytes of zeros; CC is 
the cylinder address; HH is the actual track address; 
and R is the block number. 


Are not used by the conversion routine. 


Are used by the conversion routine and are not 
restored. 


Must be loaded with the address where control is to be 
returned after execution of the conversion routine. 


Is used by the conversion routine as a base register 
and must be loaded with the address where the 
conversion routine is to receive control. 
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RETURN CODES FROM THE CONVERSION ROUTINE 


When control is returned to your program, register 15 will 
contain one of the following return codes: 





Code Meaning 
OCX'00') Successful conversion. ; 


4(X'04"') The relative block address converts to an actual track 
address outside the extents defined in the DEB 


ONVERTING AN ACTUAL TRACK ADDRESS TO A RELATIVE TRACK ADDRE 
To get the relative track address when you know the actual track 
address, you can use the conversion routine labeled IECPRLTV. 
The address of the entry point CCVTPRLTV) is in the 
communication vector table (CVT). The address of the CVT is in 
location 16. 


The conversion routine does all its work in general registers. 
You must load registers 1, 2, 14, and 15 with input to the 
routine. Register usage is as follows: 


Register Use 


0 Will be loaded with the resulting TTRO to be passed 
back to the caller. 
1 Must be loaded with the address of the data extent a 
block (DEB) of the data set. 3 
2 Must be loaded with the address of an 8-byte area 


containing the actual address to be converted to a 
TTR. The actual address is of the form MBBCCHHR. 


3-8 Are not used by the conversion routine. 

9-13 Are used by the conversion routine and are not | 
restored. | 

14 Must be loaded with the address where control is to be 


returned after execution of the conversion routine. 


15 Is used by the conversion routine as a base register 
and must be loaded with the address where the 
conversion routine is to receive control. 


ata Pay - UN NUD rm U A BLYUUR UN A VEVIVE WLI a | a4 - 


To obtain the performance improvement given by rotational 
position sensing, you should specify the sector-addr parameter 
in the XDAP macro. For programs that. can be used with both RPS 
and non-RPS devices, the UCBRPS bit (bit 3 at an offset of 17 
bytes into the UCB) should be tested to determine whether the 
device has rotational position sensing. If the UCBRPS bit is 
off, a channel program with a “set sector™ command must not be 
issued to the device. 








The sector-addr parameter on the XDAP macro specifies the 
address of a l-byte field in your region. You must store the 
sector number of the block to be located in this field. You can 
obtain the sector number of the block by using a resident 
conversion routine, IECOSCR1. The address of this routine is in 
field CVTOSCRI1 of the CVT, and the address of the CVT is in 
location 16. The routine should be invoked via a BALR 14,15 
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instruction. If you are passing the track balance to the 
routine, invoke the routine using a BAL 14,8(15). If you are 
computing the sector value on modulo devices (3375 and 3380) 
with variable length records, you must pass the track balance to 
the sector convert routine. 


For RPS devices, the conversion routine does all its work in 
general registers. You must load registers 0, 2, 14%, and 15 
with input to the routine. Register usage is as follows: 


Register Use 


0 For fixed, standard blocks or fixed, unblocked 
records not ina partitioned data set: Register 0 
must be loaded with a 4-byte value in the form XXKR, 
where XX is a 2-byte field containing the physical 
block size, K is a l-byte field containing the Key 
length, and R is a Il-byte field containing the number 
of the record for which a sector value is desired. 
The high-order bit of register 0 must be turned off 
Cset to 0) to indicate fixed-length records. 


Passing the track balance: Register 0 must be loaded 
with the 4-byte value of the track balance of the 
record preceding the required record. 


For all other cases: Register 0 must be loaded with a 
G-byte value in the form BBIR, where BB is the total 
number of key and data bytes on the track up to, but 
not including, the target record; I is a l-byte key 
indicator (1 for keyed records, 0 for records without 
keys); and R is a l-~-byte field containing the number 
of the record for which a sector value is desired. 
The high-order bit of register 0 must be turned on 
Cset to 1) to indicate variable-length records. 


1 Not used by the sector-convert routine. 


2 Must be loaded with a 4-byte field where the first 
byte is the UCB device type code for the device 
Cobtainable from UCB+19), and the remaining three 
bytes are the address of a l-byte area that is to 
receive the sector value. 


3-8 Not used. 

9-11 Used by the convert routine and are not saved or 
restored. 

12,153 Not used. 

14 Must be loaded with the address in which control is 


to be returned after execution of the sector 
conversion routine. 


15 Used by the conversion routine as a base register and 
must be loaded with the address of the entry point to 
the conversion routine. 
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The password protection described in this chapter does not apply 
to VSAM data sets. Information about VSAM data set protection 


is in Veal Administration: Macro Instruction Reference and 

e fe) es 2, For information on RACF and 
its relationship to Saeeuord protection, see RACF General 

orma . To use the data set protection feature of 


the operating system, you must create and maintain a PASSWORD 
data set consisting of records that associate the names of the 
protected data sets with the password assigned to each data set. 


Pwr ~~ mut 8 oe f 2a. 8 Fm a eet ree 


The: S ars TTGui Ways co ijiaintain tne rASONOKD data set: 
° You can write your own routines. 
@ You can use the PROTECT macro instruction. 


@ You can use the utility control statements of the IEHPROGM 
utility program. 


e If you have TSO, you can use the TSO PROTECT command. 


This chapter discusses only the first two of the four ways: It 
provides technical detail about the PASSWORD data set that is 
necessary for writing your own routines, and it describes how to 
use the PROTECT macro instruction. (The last two of the four 
ways are discussed in other publications, as indicated in the 
list of publications below.) 


Before using the information in this chapter, you should be 
familiar with information in several related publications. The 
following publications are recommended: 


° Data Administration Guide contains a general description of \ J 
the data set protection feature. oe 


e System Messages contains a description of the operator ; 
messages and replies associated with the data set protection 
feature. 


é JCL contains a description of the data definition CDD) 
statement parameter used to indicate that a data set is to 
be password protected. 


° DADSM_ and CVAF Diagnosis Guide and DADSM Diagnosis Reference 


contain 


e@ Us fetid contains a description of how to maintain the 
PASSWORD data set using the utility control statements of 
the ITEHPROGM utility program. 


° ISO Command Language Reference describes the use of the TSO 
PROTECT command. 


| : 


In addition to the usual label protection that prevents the 
opening of a data set without the correct data set name, the 
operating system provides data set security options that prevent 
unauthorized access to confidential data. Password protection 
prevents access to data sets until a correct password is entered 
by ee system operator, or, for TSO, by a remote terminal 
operator. 
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The following are the types of access allowed to 
password-protected data sets: 


e PWREAD/PWNRITE-—A password is required for read or write. 


e PNREAD/NOWRITE-—A password is required for read. Writing is 
not allowed. 


e NOPWREAD/PWWRITE—-Reading is allowed without a password. A 
password is required to write. 


To prepare for use of the data set protection feature of the 
operating system, you place a sequential data set, named 
PASSWORD, on the system residence volume. This data set must 
contain at least one record for each data set placed under 
protection. In turn, each record contains a data set name, a 
password for that data set, a counter field, a protection mode 
indicator, anda field for recording any information you desire 
to log. On the system residence volume, these records are 
formatted as a "key area™ (data set name and password) anda 
"data area™ (Ccounter field, protection mode indicator, and 
logging field). The data set is searched on the "key area." 


Note: The area allocated to the data set should not have been 
previously used for a PASSWORD data set, as this may cause 
unpredictable results when adding records to the data set. 


You can write routines to create and maintain the PASSWORD data 
set. If you use the PROTECT macro instruction to maintain the 
PASSWORD data set, see "Maintaining the PASSWORD Data Set 
CPROTECT Macro)" on page 8&8. If you use the IEHPROGM utility 
program to maintain the PASSWORD data set, see Utilities. These 
routines may be placed in your own library or in the system's 
library (CSYSI.LINKLIB). You may use a data management access 
method or EXCP programming to read from and write to the 
PASSWORD data set. 


If a data set is to be placed under protection, it must have a 
protection indicator set in its label Cformat-l1 DSCB or header 1 
tape label). This is done by the operating system when the data 
set is created, by the IEHPROGM utility program, or by the 
PROTECT macro when creating or adding the control password. The 
protection indicator is set in response to a value in the LABEL= 
operand of the DD statement associated with the data set being 
placed under protection. The publication JCL describes the 
LABEL operand. 


Note: Data sets on magnetic tape are protected only when 
standard labels are used. 


Password-protected data sets can only be accessed by programs 
that can supply the correct password. When the operating system 
receives a request to open a protected data set, it first checks 
to see whether the data set has already been opened for this job 
step. If so, only the access mode will be checked to determine 
whether it 1S compatible with the protection mode under which it 
was previously opened. If the data set has not been previously 
opened by this job step or if the access mode is not compatible 
with the protection mode under which it was previously opened, a 
message 1s issued that asks for the password; the message goes 
to the operator console. If the program requesting that the data 
set be opened is running under TSO in the foreground, the 
message goes to the TSO terminal operator. If you want the 
password supplied by another method in your installation, you 
can modify the READPSWD source module or code a new routine to 
replace READPSWD in SYS1.LPALIB. 


Chapter 4. Password Protecting Data Sets 85 


in length. 
Reference 











PASSWORD DATA SET CHARACTERISTICS 


The PASSWORD data set must reside on the same volume as your 
operating system. The space you allocate to the PASSWORD data 
set must be contiguous, that is, its DSCB must indicate only one 
extent. The amount of space you allocate depends on the number 
of data sets your installation wants to protect. Each entry in 
the PASSWORD data set requires 132 bytes of space. The 
organization of the PASSWORD data set is physical-sequential; 
the record format is unblocked, fixed-length records CRECFM=F). 
Each record that forms the data area is 80 bytes long 
CLRECL=80,BLKSIZE=80) and is preceded by a 52-byte Key 
CKEYLEN=52). The Key area contains the fully qualified data set 
name of as many as 44 bytes and a password of one to eight 
bytes, left justified with blanks added to fill the areas. The 
password assigned may be from one to eight alphameric characters 


DADSM and CVAF Diagnosis Guide an 
describe the PASSWORD data set record format. 


Note: For data sets on magnetic tape designed according to the 
specifications of the International Organization for 
Standardization (CISO) 1001-1979, the equivalent American 
National Standards Institute CANSI) X3.27-1978, or the Federal 
Information Processing Standards CFIPS) 79, do not include 
generation and version numbers as part of generation data set 
names. The generation and version numbers are not included as 
part of the names in the tape labels and are ignored if included 
in the PASSWORD data set. 


You can protect the PASSWORD data set itself by creating a 
password record for it when your program initially builds the 
data set. Thereafter, the PASSWORD data set cannot be opened 
Cexcept by the operating system routines that scan the data set) 
unless the operator enters the password. 


Note: If a problem occurs on a password protected system data 
set, maintenance personnel must be provided with the password in 
order to access the data set and resolve the problem. 


CREATING PROTECTED DATA SETS 


A data definition (DD) statement parameter CLABEL=) may be. used 
to indicate that a data set is to be password protected. For 
data sets on DASD, an alternative methed is to use the PROTECT 
macro instruction for a previously allocated data set. A data 
set may be created and the protection indicator set in its label 
aia entering a password record for it in the PASSWORD data 
set. 


Operating procedures at your installation must ensure that 
password records for all data sets currently password-protected 
are entered in the PASSWORD data set. Installations where 
independent computing systems share common DASD resources must 
ensure that PASSWORD data sets on all systems contain the 
appropriate password records for any protected data set on 
shared DASD. 


Under certain circumstances, the order in which data sets are 
allocated and unallocated from multiple systems on shared DASD 
may result in loss of password protection. For example, if an 
unprotected data set is allocated and opened by a user on System 
A and then scratched by a different user on System B, the first 
user 1S given a "window™ to the unallocated (free) area. If any 
data set, protected or unprotected, is allocated in that space 
by a user on either system during the time the "window™ is open, 
the oe data set has no protection from the user with the 
window. 


While the allocation disposition is still NEW, a 
password-protected data set can be used without supplying a 
password. However, once the data set is unallocated, any 
subsequent attempt to open will result in termination of the 
program unless the password record is available and the correct 
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password is supplied. Note that, if the protection mode is 
7 NOPWREAD and the request is to open the data set for input or 
( read backward, no password will be required. 


Tape Volumes Containing More Than One Password-Protected Data Set 


To password protect a data set on a tape volume containing other 
data sets, you must password protect all the data sets on the 
volume. (Standard labels-—SL, SUL, AL, or AUL—are required. 

For definitions of these label types and the protection-mode 
ylang a can be used, see 


If you issue an OPEN macro instruction to create a data set 
following an existing, password-protected data set, the password 
of the existing data set will be verified during open processing 
for the new data set. The password supplied must be associated 
with a PWWRITE protection-mode indicator. 


PROTECTION FEATURE OPERATING CHARACTERISTICS 


The topics that follow provide information concerning actions of 
the protection feature in relation to termination of processing, 
volume switching, data set concatenation, SCRATCH and RENAME 
functions, and counter maintenance. 


Termination of Processing 
Processing is terminated when: 


1. The operator cannot supply the correct password for the 
protected data set being opened after two tries. 


a 2. A password record does not exist in the PASSWORD data set 
ct for the protected data set being opened. 


3. The protection-mode indicator in the password record and the 
method of I/0 processing specified in the Open routine do 
not agree, for example, OQUTPUT specified against a read-only 
protection-mode indicator. 


G. There is a mismatch in data set names for a data set 
involved ina volume switching operation. This 1s discussed 
in the next paragraph. 


Volume Switching 


The system ensures a continuation of password protection when 
volumes of a multivolume data set are switched. It accepts a 
newly-mounted tape volume to be used for input or a 
newly-mounted direct access volume, regardless of its use, if 
these conditions are met: 


6 The data set name in the password record for the data set is 
the same as the data set name in the JFCB. (This ensures 
that the problem program did not changed the data set name 
in the JFCB since the data set was opened.) 


° The protection-mode indicator in the password record is 
compatible with the processing mode, and a valid password 
has been supplied. 


The system accepts a newly~mounted tape volume to be used for 
output under any of these conditions: 


e The security indicator in the HDR1 label indicates password 
protection; the data set name in the password record is the 
same as the data set name in the JFCB; and the 
protection-mode indicator is compatible with the processing 
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mode. CIf the data set name in the JFCB has been changed, a 
new password is requested from the operator. ) 


e The security indicator in the HDR1 label does not indicate 
password protection. (CA new label will be written with the 
security indicator indicating password protection.) 





e Only a volume label exists. (CA HDR1 label will be written 
with the security indicator indicating password protection. ) 


Data Set Concatenation 


A password is requested for every protected data set that is 
involved ina concatenation of data sets, regardless of whether 


the sther data sets involved are protected or not. 


SCRATCH and RENAME Functions 


To delete or rename a protected data set, it is necessary that 
the job step making the request be able to supply the password. 
The system first checks to see if the job step is currently 
authorized to write to the data set. If not, message IEC301A is 
issued to request the password. The password provided must be 
associated with a "WRITE" protection-mode indicator. 


Counter Maintenance 


The operating system increments the counter in the password 
record on each usage, but no overflow indication will be given 
Coverflow after 65535 openings). You must provide a counter 
maintenance routine to check and, if necessary, reset this 
counter. 





To use the PROTECT macro instruction, your PASSWORD data set 
bela a uh the system residence volume. The PROTECT macro can 
e use O: 


¢ Add an entry to the PASSWORD data set. 
e Replace an entry in the PASSWORD data set. 
e Delete an entry from the PASSWORD data set. 


e Provide a list of information about an entry in the PASSWORD 
data set; this list will contain the security counter, 
access type, and the 77 bytes of security information in the 
"data area" of the entry. 


In addition, the PROTECT macro updates the DSCB of a protected 
direct access data set to reflect its protection status; this 
feature eliminates the need for you to use job control language 
when you protect a data set. 


PASSWORD DATA SET CHARACTERISTICS AND RECORD FORMAT (WITH PROTECT MACRO) 


When you use the PROTECT macro, the record format and 
characteristics of the PASSWORD data set are no different from 
the record format and characteristics that apply when you use 
your own routines to maintain it 
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Number of Records for Each Protected Data Set 


_ When you use the PROTECT macro, the PASSWORD data set must 

a contain at least one record for each protected data set. The 

ee password (the last 8 bytes of the "key area™) that you assign 
when you protect the data set for the first time is called the 
control password. In addition, you may create as many secondary 
records for the same protected data set as you need. The 
passwords assigned to these additional records are called 
secondary passwords. This feature is helpful if you want 
several users to have access to the same protected data set, but 
you also want to control the way they can use it. For example: 
One user could be assigned a password that allowed the data set 
to be read and written, and another user could be assigned a 
password that allowed the data set to be read only. 


Note: The PROTECT macro will update the protection-~mode 
indicator in the format-l DSCB in the protected data set only 
when you issue it for adding, replacing, or deleting a control 
password. 


| Protection-Mode Indicator 


You can set the protection-mode indicator (third data byte) in 
the password record to one of four different values: 


9 X'00" to indicate that the password is a secondary password 
and the protected data set is to be read only CPWREAD). 


° X*80" to indicate that the password is the control password 
and the protected data set is to be read only CPWREAD). 


e X*01" to indicate that the password is a secondary password 
and the protected data set is to be read and written 
Cc CPWREAD/PWWRITE). 


e X*81l"* to indicate that the password is the control password 
and the protected data set is to be read and written 
CPWNREAD/PWWRITE). 


Because of the sequence in which the protection status of a data 
set is checked, the following defaults will occur: 


If control password is: Secondary password must be: 

1. PWREAD/PWWRITE or PWREAD/PWWRITE or 
PNREAD/NOWRITE PNREAD/NOWRITE 

2. NOPWREAD/PWNWRITE NOPWREAD/PWWRITE 


If the control password is set to either of the settings in item 
1 above, the secondary password will be set to PWREAD/PWWRITE if 
you try to set it to NOPWREAD/PWWRITE. 


If the control password is changed from either of the settings 
in item 1 to the setting in item 2 above, the secondary password 
will be automatically reset to NOPWREAD/PWWRITE. 


If the control password is changed from the setting in item 2 to 
either of the settings in item 1 above, the secondary password 
1s set by the system to PNREAD/PWWRITE. 


Because the DSCB of the protected data set is updated only when 
the control password is changed, you may request protection 
attributes for secondary passwords that conflict with the 
protection attributes of the control password. 
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| PROTECT MACRO SYNTAX 


The format is: 


indicates the location of the parameter list. The 
parameter list must be set up before the PROTECT macro is 
issued. The address of the parameter list may be passed in 
register 1, in any of the registers 2 through 12, or as an 
A-type address. The first byte of the parameter list must 
be used to identify the function Cadd, replace, delete, or 
list) you want toe perform. See Figure 16 on page J1 
through Figure 21 on page 94 for the parameter lists and 
codes used to identify the functions. 





Note: The parameter lists and the areas addressed by the list 
must reside below l6-megabyte virtual. 


o— 
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PROTECT MACRO PARAMETER LISTS 





[iz ooSSSCS~S~*dR Sing penne 


Notes: 
0 X'O1* Entry code indicating ADD function. 









G Data set name length. 
5 Data set name pointer. 


13 Control password pointer. 
The control password is the password assigned when the data set was placed 
under protection for the first time. The pointer can be 3 bytes of binary zeros 
if the new password is the control password. 


16 Number of volumes. 
If the data set is not cataloged and you want to have it flagged as protected, 
you must specify the number of volumes in this field. A zero indicates that the 
catalog information should be used. 


17 Volume list pointer. 
If the data set is not cataloged and you want to have it flagged as protected, 
you provide the address of a list of volume serial numbers in this field. Zeros 
indicate that the catalog information should be used. 


20 Protection code. 
A one~byte number indicating the type of protection: X'00' indicates default 
protection (for the ADD function; the default protection is the type of 
protection specified in the control password record of the data set); X‘'Ol1' 
indicates that the data set is to be read and written; X'02' indicates that the 
data set is to be read only; and X'03! indicates that the data set can be read 
without a password, but a password is needed to write into it. The PROTECT 
macro will use the protection code value, specified in the parameter list, to 
set the protection-mode indicator in the password record. 


21 New password pointer. 
If the data set is being placed under protection for the first time, the new 
password becomes the control password. If you are adding a secondary entry, the 
new password is different from the control password. 


24 String length. 
The length of the character string (maximum 77 bytes) that you want to place in 
the optional information field of the password record. If you don't want to add 
information, set this field to zero. 


25 String pointer. 
The address of the character string that is going to be put in the optional 
a ergo field. If you don't want to add additional information, set this 
ie o zero. 


Figure 18. Parameter List for Add Function 
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[a 000000 SSCS~*d~CR Naber of volumes 
a 


Current password pnpointer! 26 String length 





12 00 25 String pointer 
Notes: 


0 X'O02' Entry code indicating REPLACE function. 
4 Data set name length. 
5 Data set name pointer. 


9 Pointer to current password. 
The address of the password that is going to be replaced. 


13 Control password pointer. 
The address of the password assigned to the data set when it was first placed 
under protection. The pointer can be set to 3 bytes of binary zeros if the 
current password is the control password. 


16 Number of volumes. | 
If the data set is not cataloged and you want to have it flagged as protected, 
you have to specify the number of volumes in this field. A zero indicates that 
the catalog information should be used. 


17 Volume list pointer. 
If the data set is not cataloged and you want to have it flagged as protected, 
you have to provide the address of a list of volume serial numbers in this 
field. If this field is zero, the catalog information will be used. 


20 Protection code. | 
A one~byte number indicating the type of protection: X'00" indicates that the 
protection is default protection (for the REPLACE function the default 
protection is the protection specified in the current password record of the 
data set); X'Ol' indicates that the data set is to be read and written; X'02' 

 aindicates that the data set is to be read only; and X'03! indicates that the 


data set can be read without a password, but a password 1s needed to write into 
the data set. | 


21 New password pointer. 
The address of the password that you want to replace the current password. 


24 String length. 
The length of the character string (maximum 77 bytes) that you want to place in 
the optional information field of the password record. Set this field to zero 
if you don't want to add additional information. 


25 String pointer. 
The address of the character string that 1s going to be put in the optional 
information field of the password record. Set the address to zero if you don't 
want to add additional information. 


Figure 19. Parameter List for REPLACE Function 
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Notes: 
0 X'03* Entry code indicating DELETE function. 








4 Data set name length. 
5 Data set name pointer. 


9 Current password pointer. 
The address of the password that you want to delete. You can delete either a 


control entry or a secondary entry. 


13 Control password pointer. 
The address of the password assigned to the data set when it was placed under 
protection for the first time. The pointer can be 2 bytes of binary zeros if 
the current password is also the control password. 


16 Number of volumes. 
If the data set is not cataloged and you want to have it flagged as protected, 
you must specify the number of volumes in this field. A zero indicates that 
the catalog information should be used. 


17 Volume list pointer. 
If the data set is not cataloged and you want to have it flagged as protected, 
you must provide the address of a list of volume serial numbers in this field. 
If this field is zero, the catalog information will be used. 


Figure 20. Parameter List for DELETE Function 
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0 X*04! | 5 Data set name pointer 
4 Data set name length 9 Current password pointer 


Notes: 






0 X'04* Entry code indicating LIST function. 


1 80—-byte buffer pointer. 
The address of a buffer where 
program by the macro instructi 


sf information can be returned to your 


© ct 
0 
put 
el 
v) 


n. 
G Data set name length. 

5 Data set name pointer. 

9 Current password pointer. 


The address of the password of the record that you want listed. 


Figure 21. Parameter List for LIST Function 
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RETURN CODES FROM THE PROTECT 
When the P 
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MACRO 


ROTECT macro finishes processing, register 15 contains 


one of the following return codes: 


Code 
0€X*00*) 
40X"04") 


8(X*08") 


12€X*"0C') 


16(X*10") 


200X*14") 
24(X*18!")32 
28(X*1C") 
32¢X'20')2 


36€X'24')2 


40€X*28'")2 
44(CX*2C') 

48(X'30')2 
52CX"32')2 


Notes: 


Meaning 
The PASSWORD data set was successfully updated. 


The PASSWORD of the data set name was already in the 
password data set. 


The password of the data set name was not in the 
PASSWORD data set. 


A control password is required or the one supplied 
1S incorrect. 


The supplied parameter list was incomplete or 
incorrect. 


There was an I/0 error in the PASSWORD data set. 

The PASSWORD data set was full. 

The validity check of the buffer address failed. 

The LOCATE macro failed. LOCATE's return code is in 
register 1, and the number of indexes searched is in 


register 0. 


The OBTAIN macro failed. OBTAIN's return code is in 
register l. 


The DSCB could not be updated. 
The PASSWORD data set does not exist. 
Tape data set cannot be protected. 


Data set in use. 


For this return code, a message is written to the 
console indicating that the PASSWORD data set is full. 


For this return code, the PASSWORD data set has been 


updated, but the DSCB has not been flagged to indicate 
the protected status of the data set. 


Chapter 4. Password Protecting Data Sets 95 

















THE EXIT MODULES 


| THE EXZT ENVIRONMENT 
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This chapter discusses how installation-written exit modules 
can: 


e Take control before and after direct access device storage 
management CDADSM) processing 


e Take control during Open for a DCB 


e Determine whether a missing data set control block Csuch as 
for a data set that has been moved to anotner volume) can be 
restored to a volume 


e Recover from errors that may occur during the opening, 
closing, or handling of an end-of-volume condition for a 
data set associated with the user's task 


Notes: 


1. For information about other available installation-written 
exits, see ini j i 


2. For information on IBM-supplied exits for tapes with 
International Organization for Standardization (ISO), 
American National Standard Institute CANSI), or Federal 
Information Processing Standards (FIPS) labels, see 


ANY POST PRULEOCOLAN Pe KUVUELINGEs 


There are exit routines to enable an installation-written module 
to take control before and after DADSM processing. An exit 
parameter list is used to communicate with DADSM. The format of 
this parameter list is shown in Figure 22 on page 98. 


All DADSM functions Callocate, extend, scratch, partial release, 
and rename) have a common preprocessing exit routine and a 
common postprocessing exit routine that the installation exit 
routine can replace. These exit routines enable you to gain 
control before and after DADSM processing. The preprocessing 
exit routine module is IGGPREO00; the postprocessing exit routine 
module is IGGPOST0O. Each is used by all the DADSM functions 
listed above. The modules reside in SYSI1.LPALIB. You can use 
System Modification Program CSMP) to replace the IBM-supplied 
poh routine modules with an installation exit routine you 
write. 


The exit routines are given control in supervisor state and 
protect key zero with no locks held. DADSM assumes that the 
exits are AMODE=24 and RMODE=24. The exit routines must be 
reentrant. DADSM or the program that invokes DADSM (by issuing 
enqueue, reserve, and so forth) will have acquired the system 
resources needed to serialize system functions. These enqueues 
may prevent other system services from completing successfully. 
In particular, exit routines must not issue dynamic allocation, 
OPEN, CLOSE, EOV, LOCATE, and other DADSM functions because they 
issue an enqueue on the SYSZTIOT resource. If the exit routines 
require access to an installation data set, the control blocks 
required to access that data set (DCB, DEB) should be built 
during system initialization CIPL/NIP). 
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The type and number of resources held by DADSM depend upon the 
DADSM function and the exit taken. For example, on entry to the 
installation preprocessing exit CIGGPRE00), DADSM holds an 
enqueue on the VTOC and a reserve on the device for the subject 
volume of a SCRATCH, RENAME, or partial release function. DADSM 
releases these resources before the installation postprocessing 
exit CIGGPOSTO) takes control. 


You must anticipate system resource contention when services are 
requested from an exit routine. For example, RACF services 
issue an enqueue on the RACF data set or a reserve on that data 
set's volume. This contention can cause system performance 
problems or an interlock condition. 


WHEN IGGPREOO GETS CONTROL 


The preprocessing exit routine, IGGPRE00, is given control 
before the first VTOC update and after the initial validity 
check is successful. Input to IGGPREOO is a parameter list, 
mapped by macro IECIEXPL, that contains addresses of input data 
and a function code that identifies the DADSM function. 

IGGPREOO is given control once for each volume in the volume 
list supplied to scratch and rename. A field in the parameter 
list, IEXRSVWD, may be used to pass data from the preprocessing 
exit routine to the postprocessing exit routine. 


A zero return code from IGGPRE00 indicates the DADSM function 
may proceed. 


| REJECTING A DADSM REQUEST 


A preprocessing exit routine may reject a DADSM request, in 
which case an I/0 error return code is generated for all 
functions except allocate and extend. A return code of 4 or 8 
from IGGPREOO to allocate will cause allocate to return X'"BG* or 
X* BO", respectively, to its caller in register 15. Scheduler 
allocation will treat a X'BG' as a conditional rejection of the 
allocate request only for the volume being processed. If the 
allocate request is not for a specific volume, another volume 
may be chosen and the allocate function retried. Scheduler 
allocation will treat a X'BO' return code from allocate as an 
unconditional rejection of the allocate request. If the 
allocate request is rejected, the preprocessing exit routine can 
put a reason code in the parameter list field, IEXREASN, and the 
code will be returned by allocate to its caller, together with 
the X'"BO! or X'B4!' return code in register 15. The reason code 
will appear in the JCL error message if the allocate request is 
not retried. A nonzero return code from IGGPREO0O to extend will 
cause extend to return an error return code of X'FFFF FFEC*® to 
its caller. If the caller is end-of-volume, an E37-0C abend 
will be issued. 7 
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DATA THAT DADSM PASSES TO THE EXITS 








The format of the parameter list CIEPL) is shown in Figure 22 on 





page 98 | 
Name Offset Bytes Description 
IEXID OOCX*'O00') G . EBCDIC 'IEPL'* 
IEXLENG 04€X'04!') 1 Length of parameter list 
IEXFUNC O5¢€X"05') 1 DADSM function code: 
ILEXALL X?*01'-Allocate | 
ITEXEXT X'02'-Extend 
ITEXSCR X*'03'-Scratch 
IEXPR X'04'-Partial release 
TEXREN x*05* ~-KRename 
ITEXEXTCD 06(X'06!°) 1 Extend code 
X'O1l"* Extend data set on current volume 
X*'02*' Extend an OS catalog on current volume 
X'04* Extend data set on new volume 
X'*81* Extend VSAM data space on current 
volume 
IEXFLAG 070X"07') 1 Flag byte 
ITEXENQ i nee VYTOC is enqueued upon entry 
ITEXVIO Slee ea VIO data set 
TEXMF1 Por ier IEXFMT1 points to DXI1FMTID of a partial 
format-l1 DSCB Cpartial DSCB passed as input 
to allocate, and not JFCB is not available). 
% 02 eX XXXX Reserved 
IEXREASN 08CX*'08") 2 Installation reject reason code 
¥ 2 Reserved 
ITEXUCB 12¢X'0C*) 4 Address of UCB. The UCB address is not 
available to the pre-~exit for VIO allocation. 
IEXPTR1 16CX'10') G Address of the following: 
‘ne JFCB Callocate, extend, partial 
release) 
_ Scratch/rename input parameter list 
Cin user storage) 
IEXPTR2 20¢€14) G Address of the following: 
- DSAB list CISAM allocate) 
= DEB CExtend on old volume) 
_- DCB Cpartial release) 
= Current volume list entry 
Cscratch/rename) 
IEXDSN 24CX'18°) G Address of the data set name 
TEXFMT1 28CX'1C') G Address of the 96-byte data portion of 
format~1 DSCB (pre exit for scratch; pre and 
post exit for partial release and rename; 
post exit for allocate). May be supplied by 
pre exit of allocate, and extend on new 
volume, to serve as a model if ITEXMFl1 and 
IEXVIO are zero. 
LEXFMT2 320X'20') G Address of format-2 DSCB. CISAM allocate 
post exit.) | 
ITEXRSV00 S6CX'24") | Reserved 


Figure 22 (Part 1 of 2). 
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Format of DADSM Preprocessing and Post-processing Exit 
Parameter List 
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Name Offset Bytes Description 


( ITEXEXTBL 40CX*28!') G Address of DADSM table Cpre- and post~exit 

be for scratch and partial release; post-exit 
for allocate and extend). For VIO allocate 
post-exit, this is the address of DSILEXT1 in 
the virtual FMl1 DSCB. 

| IEXDCC GGCX*2C*) G DADSM completion code Cpost exit) 
IEXRSVWD G8CX'30') 4 Reserved word for use by installation exit. 

Some of the fields passed to the post-exit 
Csuch as IEXUCB for VIO allocation) may be 
successful. 





Figure 22 (Part 2 of 2). Format of DADSM Preprocessing and Post-processing Exit 
Parameter List 


PASSING A MODEL FORMAT=-1 DSCB 


The preprocessing exit for allocate and extend on a new volume 
may return, in the parameter list field IEXFMT1, the address of 
the data portion of a model format~-l DSCB, starting with field 
DSLFMTID. The DSCB will be moved to the allocate or extend work 
area before building the format-1 DSCB. The only fields that 
may be nonzero in the area are the DSIREFD (the 
data-last-referenced field) and fields currently unused. 

Failure to zero out all fields, except for DSIREFD and all 
currently unused fields in the model format-1 DSCB, can result 
in the abnormal termination of the task or lead to unpredictable 
Reirbeta All other fields will be initialized by allocate or 
extend. 


IEXFMT1 may not be supplied by IGGPREO00 for a VIO allocate 
request Cindicated by flag, IEXVIO, set to one), or, if a 
partial DSCB instead of a JFCB has been supplied to allocate 
Cindicated by flag, IEXMFl, set to one). In the latter case, 
IEXFMT1 is passed to IGGPRE0O0 initialized to the address of the 
DS1FMTID field of the partial format-1l DSCB Csupplied to : 
allocate by its caller) in the allocate work area, and DSIREFD 
may be initialized by IGGPRE00. If extend was successful, 
IEXFMT1 is zeroed out prior to taking the post-exit, IGGPOSTO. 





WHEN IGGPOSTO GETS CONTROL 


The postprocessing exit module, IGGPOSTO, is given control after 
a DADSM function has been completed or attempted. IGGPOSTO is 
given control if IGGPRE00 was given control, whether the DADSM 
function was successful or not. IGGPOSTO is not given control 
if IGGPREO0O was not given control, or if the DADSM function 
terminated abnormally. IGGPRE00 may establish a recovery 
routine, if required, to clean up system resources. The DADSM 
recovery routine does not give IGGPOSTO control. Input to 
IGGPOSTO is the same parameter list passed to IGGPRE00. No 
return codes from IGGPOSTO are defined. 


| SYSTEM CONTROL BLOCKS 


The DADSM installation exit parameter list contains the address 
of system control blocks. The mapping macros of those control 
blocks are listed below, together with the name of the system 
library on which they reside. One of the macros, ICVARXNT, is 
only supplied with the optional material 
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There is no mapping macro for the SCRATCH/RENAME parameter list 
or the associated volume list. 


For extend and‘ partial release, the address of the JFCB passed 
to the user exit points to a copy of the real JFCB. Updating 
lata og JFCB will not result in a corresponding change to the 
rea B. 


During EXTEND of a VSAM data set, the exit is passed the address 
of a dummy DEB. This DEB does not contain any EXTENT 


information. 


REGISTERS AT ENTRY TO DADSM EXITS 


REGISTERS AT RETURN 


At entry to your exit routine, register contents are as follows: 


Register Contents 
1 Address of the exit parameter list 


13 Address of an 18-word save area 
14 Return address to DADSM 
15 Address of your exit routine 


FROM DADSM EXITS 

When you return to DADSM, register contents must be as follows: 
Register Contents 

0-14 


Same as on entry to your exit routine 
15 A return code from IGGPREOO 


| RETURN CODES FROM DADSM EXITS 


No return codes are defined for IGGPOSTO. The IGGPREOO return 
codes and their meanings are as follows: 


Code Meaning 


00CX*00"') Indicates that you want the DADSM request to be 
processed 


040X'04') Indicates that no DADSM request for the current volume 
is to be processed 


O08€X'08') Indicates that you do not want the DADSM request to be 
| processed 


DCB_ OPEN INSTALLATION EXIT 


There is an exit that enables an installation-written module to 
take control during Open for a DCB. An exit parameter list is 
used by open processing to communicate with the exit module. 

The ie of the parameter list is shown in Figure 23 on 

page ‘ 
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THE EXIT MODULE 


THE EXIT ENVIRONMENT 


OPEN has an exit module that the installation can replace. This 
module is IFGOEX0B that resides in load module IGCOOO1I. The 
load module resides in SYSI1.LPALIB. You can use System 
Modification Program (SMP) to replace the IBM-supplied exit 
module with an installation exit you write. 


IFGOEXOB is given control in supervisor state and protect key 
zero with no locks held. System enqueues will have been issued 
to serialize system functions. These enqueues may prevent other 
system services from being invoked. In particular, dynamic 
allocation, OPEN, CLOSE, EOV, and DADSM functions should not be 
invoked because of an enqueue on the SYSZTIOT resource. If the 
exit requires access to an installation data set, the control 
blocks required to access that data set CDCB, DEB) should be 
built during system initialization CIPL/NIP). RACF macros may 
be invoked from the exit. 


OPEN PROCESSING BEFORE THE DCB OPEN EXIT GETS CONTROL 


The exit module, IFGOEX0B, is given control whenever OPEN 
finct cone Reva, been, partoraed gar aha Dena 
e DASD data sets 

—- Volume mounted 

= Format-l, -2, and -3 DSCBs read 

- Forward merge from format-1 DSCB to JFCB 
. Tape data sets 

— Volume mounted 

= Header labels verified 

= Forward merge from header labels to JFCB 
¢ All data sets 

= Forward merge from JFCB to DCB 

— User DCB OPEN installation exit (if any) taken 


_ RACF or password verification processing 


OPEN PROCESSING AFTER THE DCB OPEN EXIT GETS CONTROL 


The following functions have not yet been performed at the time 
the exit is given control for the DCB. 


e Reverse merge from DCB to JFCB (not all fields are merged) 


e Reverse merge from JFCB to format-l DSCB for DASD data sets 
(not all fields are merged) 


® Header labels written (for output tape data set) 


e Access-~method-dependent processing Cobtain buffers, GETMAIN, 
and build IOQBs and DEB) 


® Write JFCB 
e Write format-1 DSCB 
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GETTING CONTROL FROM OPEN 


DATA THAT OPEN PASSES TO THE EXIT 


Name 
OTEXL 


OLTEXOOPT 
OITEXRSVD 
OITEXOOUT 
OITEXOOIN 
OITEXOUPD 
OITEXOINO 
OTEXORDB 
OITEXOINP 
OTEXUKEY 


OTEXLTH 
OITEXUDCB 


OLEXPDCB 


OITEXJFCB 
OLEXDSCB 


OITEXTIOT 
OITEXUCB 


Figure 23. 











The exit is given control for each DCB being opened, even when 
two or more DCBs are being opened in parallel with one 
invocation of OPEN. 


The exit is given control from OPEN (SVC 19) and OPEN TYPE=J 


CSVC 22). 


The exit is given control from end-of-~volume CEOV; 


SVC 55) and from force-end-of-volume CFEOV; SVC 31) when a 
concatenation of two sequential data sets with unlike attributes 


is being processed. 
which gives control to OPEN. 


like attributes is being processed. 
give control to CLOSE and OPEN. 


flag DCBOFPPC Cbit 4; 
one. 


In 


this case, EOV 


gives control to CLOSE, 


The exit is not given control 
from EOV when a concatenation of two sequential data sets with 


In t 


his case, EOV does not 


A request by the user proaram 
for concatenation with unlike attributes is shown in the DCB by 


mask X'08') in field DCBOFLGS being set to 


The parameter list mapped by macro IECOIEXL is supplied to the 


installation exit. 


It contains data and the addresses of 


control blocks that may be of interest to the exit. 


The format of the parameter list is shown in Figure 23 on 


page 102 


Offset 
00¢00) 


00¢€00) 


01¢01) 


02¢(02) 
04004) 


08003) 


12C0C) 
16€10) 


20014) 
24018) 


Bytes 

0 

1 

IO ip Ree 

64g, Lhe 
ace aah 
cate. eve 

; aes 

; seek 

ue eis 

2 

4G 

4 

4 

4 

4 

4 


Description 

DCB Open installation exit 
parameter list 

Open option Clast 4 bits). 
X'FO' first 4 bits reserved. 
15 output 


outin 


inout 


OmMN A~] 


input 


update 


read backward 


User protect key. Key of user 


CB. 
Length of OITEXL 


Address 
protect 
Address 


of user DCB in user 
key COIEXUKEY) 
of protected copy of DCB 


used by OPEN 


Address 
Address 


of JFCB 
of data portion of 


format-1l DSCB 


Address 
Address 


of TIOT entry 
of UCB 


Format of DCB OPEN Installation Exit Parameter List COIEXL) 


Note that two DCB addresses are supplied. OPEN maintains a 


protected copy of your D 


to test the DCB fields. 
OPEN updates its protected copy when it regains control from the 


exit. 
parameter list. 
from or modify your DCB. 


You can use OPEN's copy of the DCB 
If you modify your copy of the DCB, 


The protect key of your DCB is supplied in the exit 
You must use this Key to either get information 


Be sure you determine the type of DCB and device passed to the 
exit before testing access~method or device-dependent fields in 


the DCB. 


The sample exit shown in Appendix D, "Example of an 


OPEN Installation Exit Module™ on page 225 gives an example of 
isolating a QSAM DCB being opened to a DASD or tape device. 


The JFCB address supplied to the exit points to a copy of the 


JFCB that is in the OPEN work area. 
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There may be other JFCBs 
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associated with the OPEN if ISAM or concatenated partitioned 
data sets are being opened. 


In the case of BDAM, ISAM, and concatenated partitioned data 
sets, the UCB, whose address is supplied to the exit, may not be 
the only UCB associated with the DCB being opened. The UCB 
should not be modified. 


The TIOT address supplied is of a TIOT entry CTIOENTRY label in 
the ITEFTIOT1 macro). In the cases of ISAM and concatenated 
partitioned data sets, other TIOT entries may be associated with 
the DCB being opened. If concatenation of unlike attributes is 
being processed, the TIOT entry may have a blank DDNAME field. 


The format-l DSCB passed to the exit is in the OPEN work area. 
The address is that of the field DSIFMTID. There may be 
format-2 and -3 DSCBs associated with the format-1 DSCB. There 
may be other format-] through -3 DSCBs associated with the DCB 
being opened in the cases of ISAM, BDAM, and concatenated 
partitioned data sets. If the OPEN is to the VTOC, a format-4 
DSCB address is passed to the exit; this can be determined by 
testing field DSIFMTID for a value of X'F4"', or the data set 
name in the JFCBDSNM field of 44X'04¢'. 


| DEFAULTING THE DCB BUFFER NUMBER 


MODIFYING THE JFCB 


If a value has not yet been supplied, the exit may be used to 
supply an installation-determined value for DCBBUFNO (Cnumber of 
buffers) for QSAM DCBs. 


A sample exit program that does this is shown in 
seer D, "Example of an OPEN Installation Exit Module” on 
page 


You should not override a nonzero value in DCBBUFNO for QSAM 
DCBs without Knowing what dependency the user program has on 
that value. When a buffer pool control block address is in the 
DCB field DCBBUFCA, you cannot override DCBBUFNO; this indicates 


that buffers have been acquired before OPEN. If no buffer pool 


control block address exists, DCBBUFCA is set to one (not zero). 


You should not override a zero value in DCBBUFNO for BSAM DCBs 
when DCBBUFCA is set to one without knowing what dependency the 
user program has on these values. If the user program does not 
want OPEN to acquire buffer storage space, it indicates this by 
setting DCBBUFNO to zero and DCBBUFCA to one. If the user 
program wants OPEN to acquire buffer storage space, it can 
override DCBBUFNO with a nonzero value. The user program is 
then responsible for freeing that space after closing the DCB. 


Whenever the JFCB is modified, code 4 should be returned to 
OPEN. This will cause OPEN to rewrite the JFCB. The JFCB should 
not be modified if the user program has set JFCNWRIT Cbit 4) in 
ee ee because it indicates the JFCB should not be 
written. 


A sample exit program that modifies the JFCB is shown in 


Appendix D, "Example of an OPEN Installation Exit Module™ on 
page 225. 
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Requesting Partial Release 


An example of modifying the JFCB in OPEN's work area to request 
partial release is shown in Appendix D, "Example of an OPEN 
Installation Exit Module™ on page 225. It sets the following 
bits to 1, indicating a partial release request: JFCRLSE (Cbits 
0 and 1; mask X'CO') in byte JFCBIND1L. This should be done only 
for DASD physical-sequential or partitioned data sets opened for 
OUTPUT or OUTIN and processed by either (1) EXCP with a 5-word 
ee section present in the DCB, €2) BSAM, or (3) 


Care should be taken in modifying the JFCB release bits. For 
example, a data set that is opened for output many times, 
writing varying amounts of data each time, may have to extend 
after each OPEN, resulting in many small extents and, perhaps, 
reaching the l6é-extent limit. This could result in a B37 abend. 


Care should also be taken in setting the JFCBSPAC bits to define 
the space quantity units when the partial release flag, 
JFCBRLSE, is also set on. A cylinder allocated extent may be 
released on a track boundary when JFCBSPAC does not indicate 
cylinder units or average block length units with ROUND 
specified. This will cause the cylinder boundary extent to 
become a track boundary extent, thereby losing the performance 
advantage of cylinder boundary extents. Zeroing the release 
indicator and increasing secondary allocation quantity (fer 
example, when the data set has extended a large number of times) 
may prevent such a B37 abend. Setting the release indicator 
could result in more space being made available to other users 
sharing the volume. 





Updating the Secondary Space Data 


The JFCB may also be modified by updating the secondary space aa 
data. Byte JFCBCTRI contains the space request type coded in if : 
the DD statement or merged from the format-1l DSCB. Field Sw 


JFCBSQTY contains the amount of secondary space Cin either 
tracks, cylinders, or average block units). Field JFCBPQTY 
contains the amount of primary space (Cin either tracks, 
cylinders, or average block units). 


Setting the contiguous bit CJFCONTIG) to zero may prevent an 

out-of-space abend where there is enough space, but not enough 

contiguous space, to satisfy a request to extend the data set. 
REGISTERS AT ENTRY TO THE DCB OPEN EXIT 


At entry to the exit, register contents are as follows: 


Register Contents 


1 pe of the DCB OPEN installation exit parameter 
is 

13 Address of an 18-word save area 

14 Return address to OPEN 

15 Address of the entry point to IFGOEXOB 
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REGISTERS AT RETURN FROM THE DCB OPEN EXIT 


When you return to OPEN, register contents must be as follows: 
Register Contents 
0-14 Same as on entry to the exit. 


15 A return code from IFGOEXOB 


RETURN CODES FROM THE DCB OPEN EXIT 


The DCB OPEN exit must pass a return code back to OPEN in 


register 15. The return codes and their meanings are as 
follows: 
Code Meaning 


OOCX"'00') Indicates that the JFCB has not been modified 
04€X'0G') Indicates that the JFCB has been modified 





The function of the format-l DSCB-not-found installation exit in 
OPEN and EOV is to determine whether a missing DSCB (such as a 
data set that has been migrated to another volume) can be 
restored to the volume. If your exit module restores the DSCB, 
it indicates this when it returns control to the control 
program. The exit module, IFGOEXO0A, is given control whenever 
OPEN or EOV fails to find a format-l DSCB on a volume. There is 
an IBM-supplied exit module, IFGOEX0A, in SYSI1.LPALIB. If you 
want to use your own exit module, you must replace IFGOEXOA. 
Your exit module must have an entry point name of IFGOEXOA. If 
you do not write your own exit module, processing continues 

Ae Baal aed because the IBM-supplied exit returns a zero return 
code. 


The exit is taken even under conditions under which abnormal 
termination ordinarily would not occur. Two examples of these 
conditions follow: 


1. When you have specified DISP=MOD and error recovery 
processing is taking place because the last volume specified 
in the JFCB does not contain the DSCB, but an earlier volume 
does. For this case, if your return code from IFGOEX0A is 0 
or if your return code is 4 and the DSCB has not been 
restored, OPEN and EOV search the other volumes for the DSCB 
after the exit is taken. 


2. Another condition occurs during EOV output when space has 
not yet been allocated on the new volume. Space is 
allocated after the exit is taken if your return code from 
IFGOEXOA is 0 or if your return code is 4 and the DSCB has 
not been restored. 


When a DSCB is not found, IFGOEXO0A is given control as follows: 

e In system protect key 5 (data management Key) 

e In supervisor state 

e The system resource represented by the SYSZTIOT major name 
is enqueued for shared control. (This ENQ@ prevents the exit 


from invoking system functions such as SCRATCH, RENAME, 
dynamic allocation, or LOCATE.) 
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DATA THAT OPEN/EOV PASSES TO THE EXIT 


The parameter list pointed to by register 1 consists of two 
fullwords. The first fullword contains the address of the UCB 
of the volume for which the format-l DSCB was not found. The 
second fullword contains the address of the 44-byte data set 
name, left justified, and padded with blanks. Bit zero of the 
second fullword is set to one, indicating the last word in the 
parameter list. 





The data set name must not be modified by the exit. The 
parameter list, save area, and data set name are in protect key 
5 virtual storage, which is not fetch protected. IFGOEX0A must 
be reenterable. All work areas obtained through GETMAIN must be 
released through FREEMAIN. | 


REGISTERS AT ENTRY TO THE FORMAT=1 DSCB NOT FOUND EXIT 
At entry to your exit routine, register contents are as follows: 
Register Contents 
0 If X'00", entry was from OPEN (single volume data 


set). If X'0C*", entry was from OPEN (multivolume data 
set). If X'OF', entry was from EOV. 


1 Address of the parameter list 

2-12 Unpredictable 

13 Address of an 18-word save area 

14 Return address to OPEN/EOV 

15 Address of entry point to IFGOEXOA 


REGISTERS AT RETURN FROM THE FORMAT=1 DSCB NOT FOUND EXIT 


When you return to OPEN/EOV, register contents must be as 
follows: 


Register Contents 
2-12 Same as on entry to the exit 


15 A return code from the exit 
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RETURN CODES FROM THE FORMAT-1 DSCB NOT FOUND EXIT 


The format~-1l DSCB not found exit must pass a return code back to 
OPEN/’EOV as follows: 


Code Meaning 
0O0CX'00") Processing continues normally. 


This return code is given if the exit does not restore 
the DSCB. The IBM-supplied exit module always gives 
return code 0. 


04€X'04') The volume is searched one more time by OPEN or EOV 
for the DSCB. This return code is given if IFGOEXO0A 
restores the DSCB to the volume. If the DSCB is again 
not found, IFGOEX0OA is not given control and 
processing continues normally. 


O08CX'08"') The task is abnormally terminated without attempting 
to determine if DISP=MOD error recovery or allocation 
on the new volume should occur. This return code is 
given if IFGOEX0OA encounters an error and you do not 
want to continue processing. 


You should have IFGOEX0A establish its own error recovery 
environment Cfor example, through an ESTAE), intercept any 
indeterminate errors, and return to the control program with 
return code 8. Problem determination is the responsibility of 
your exit module. A write-to-programmer CWTO with routing code 
11) or a TPUT Cif a TSO region) may be used to issue an 
informative message. 


During a parallel OPEN when two or more DCBs are being opened at 
the same time and two of the DCBs are opening the same data set, 
the DSCB may be missing. If IFGOEX0A is called for the first of 
the two DCBs and restores the DSCB, the channel program 
attempting to read the DSCB for the second DCB may have been 
executed before the restoration of the DSCB was complete. 
IFGOEXOA is then called for the second DCB, even though the DSCB 
has already been restored. Return from IFGOEXOA with a return 
code 4 1S appropriate in this case. 


IFGOEX0A is not given control when you are processing a VSAM 
data set with an ACB; however, it is given control when you are 
processing a VSAM data space with a DCB. IFGOEX0A is bypassed 
if the format-4 DSCB is not found on a volume, even if the OPEN 
Cr ids VTOC data set name (data set name of 44 bytes of 





The abend installation exit provides the ability to recover from 
abnormal conditions that may occur during the opening, closing, 
or handling of an end-of-volume condition for a non-VSAM data 
set associated with the user's task. 


When an abnormal condition occurs, control passes to the DCB 
abend user exit routine if one is provided, and processing 
continues as specified in the DCB abend user exit routine. (The 
DCB abend user exit routine gives you some options regarding the 
actions you want the system to take when a condition arises that 
may result in abnormal termination of your task. For additional 
information about | the DCB abend user exit routine, see Data 

: However, if the DCB abend user exit 
routine 1s not specified, or if it specifies immediate abnormal 
termination of the task, the system passes control to the abend 
installation exit. If a DCB abend user exit routine is not 
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Boye control immediately passes to the abend installation 
exit. | 





IBM supplies an installation exit module, IFG0O199I in 
SYSI.LPALIB, that handles abend situations caused by tape 
positioning errors. IFG0199I allows you to retry tape 
positioning when you receive a system completion code 613 with 
return code 08 or OC. To perform recovery actions for data 
management abend situations Cother than those caused by tape 
positioning errors), you can replace installation exit module 
IFGO199I by modifying the source code supplied in SYS1.SAMPLIB. 
IFGO199I receives control in protection Key zero, supervisor 
state. IFGO199I checks the system completion code and the 
return code to determine whether the abend situation is the 
result of a tape positioning error. If the svstem completion 
code is other than 613 with return code 08 or OC, control 
returns to the calling module with return code 0, indicating 
that the abend should continue. Otherwise, IFGO0199I checks the 
counter in the 4$~byte work area to determine whether one attempt 
to reposition the tape has been made. If no attempt to | 
reposition the tape has been made, IFGO0199I issues a return code 
of 4, indicating that positioning should be retried. If one 
attempt to reposition the tape has been made, IFG0199I issues 
message IEC613A to the operator to determine whether to attempt 
repositioning. If the operator specifies that tape positioning 
is to be attempted again, a return code of 4 is set, indicating 
that OPEN is to rewind the tape and attempt positioning. If the 
operator specifies that tape positioning is not to be retried, 
control is returned to the calling module with a 0 return code. 


DATA THAT OPEN/“EOV PASSES TO THE EXIT 


The format of the parameter list COAIXL) is shown in Figure 24. 


Word Boundary oN 


+4004) Address of the protected copy of the DCB 

+8 (08) Address of the user's DCB related to the abend 
#1200C) 7 Address of the UCB related to the abend 
+16€010) | Address of the JFCB related to the abend 
#200149) Address of the TIOT related to the abend 
#24(18) Abend code — Example X'6130000C" 


+28C1C) | G—-byte installation work area 


1(€01) Option flags: 
Bits 


0 indicates whether the DCB abend 
user exit was taken 


On exit was taken 
Off exit was not taken 


l indicates whether to rewind the 
tape volume 


On rewind the tape volume 
Off do not rewind the tape volume 
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REGISTERS AT ENTRY TO THE DATA MANAGEMENT ABEND EXIT 


REGISTERS AT RETURN 


At entry to the exit routine, register contents are as follows: 


Register Contents 


1 Address of the parameter list COAIXL) 
13 Address of an 18-word save area 

14 Return address to OPEN/EOV 

15 Address of the entry point to IFG0199I1 


FROM THE DATA MANAGEMENT ABEND EXIT 


When you return to OPEN/EOV, register contents must be as 
follows: 


Register Contents 
2-12 Same as on entry to the exit 


15 A return code from the exit 


| RETURN CODES FROM THE DATA MANAGEMENT ABEND EXIT 


The data management ABEND exit must pass a return code back to 
OPEN/EOV as follows: 


Code Meaning 


00CX'00') Continue with the abend in process. 


046(0X'0G') If the bit 1 option flag is on, rewind the tape volume, 


set the UCBFSCT and UCBFSEQ fields in the UCB to zero, 
and retry the abend in process. 


If the bit 1 option flag is off, retry the abend in 
process. 


For abend codes that the installation is allowed to retry, see 
the DCB Abend Exit section in Chapter 7 of the 
fe) . 


Modifying the IBM-Supplied Installation Exit Module: Because 
the IBM-supplied installation exit module handles only a 
particular abend situation, you may want to modify the source 
code of that module to perform corrective actions for other 
abend situations. 


You can obtain a copy of the source code from SYS1.SAMPLIB for 
modification, using the editing function that is available to 
you. After you have modified the source code, link-~edit it into 
SYSI1.LPALIB. The source program is written in Assembler 
language and uses only macros in SYSI1.MACLIB. If you replace 
the supplied installation module, the exit module that you 
supply must have the entry point name IFG0O199I and it must be 
reenterable. 
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This chapter describes miscellaneous macro instructions that 
allow you to: 


° Modify control blocks CRDJFCB macro) 


e Obtain information from control blocks and system tables 
CDEVTYPE macro) 


@ Perform track capacity calculations CTRKCALC macro) 
e Allocate a data set based on a partial DSCB CREALLOC macro) 


® Load a message display on an IBM 3480 Magnetic Tape 
Subsystem CMSGDISP macro) 


Before reading this chapter, you should be familiar with the 
following publications: 


e ssem 3 


a 
contains the information necessary to code programs in the 
assembler language. 


6 Debugging Handbook contains format and field descriptions of 
the data areas referred to in this chapter. 


| INTRODUCTION 
The system macro instructions are described in these functional 
groupings: 
e Mapping CIEFUCBOB, IEFJFCBN, and CVT) 
° Obtaining device characteristics (CDEVTYPE) 
e Manipulating the JFCB CRDJFCB) 
e Data security CDEBCHK) 
e Manipulating queues CPURGE and RESTORE) 
e Performing track capacity calculations CTRKCALC) 
e Allocating a DASD data set CREALLOC) | 
° sacar ies Meeeapeoa Pe on an IBM 3480 Magnetic Tape 
MAPPING SYSTEM DATA AREAS 


The IEFUCBOB, IEFJFCBN, and CVT macro instructions are used as 
DSECT expansions that define the symbolic names of fields within 
the unit control block (CUCB), job file control block (CJFCB), and 
communication vector table (CVT), respectively. 


The CVT, IEFUCBOB, and IEFJFCBN macro definitions are in a 
distribution library named SYS].AMODGEN. Before you can issue 
the macros, you must copy them from SYS1.AMODGEN into 
SYS1.MACLIB (the IEBCOPY utility can be used to copy the 
macros), or SYS1.AMODGEN may be concatenated to the macro 
library before reference is made to SYS1.AMODGEN. 


The fields in these blocks are shown and described in Debugging 
Handbook. 
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IEFUCBOB——MAPPING THE UCB 


in the unit control block CUCB). The macro does not include a 
DSECT statement. However, if you specify PREFIX=YES, the DSECT 
statement is provided. 


( This macro instruction defines the symbolic names of the fields 


The format is: 


[symbol] ] IEFUCBOB; [LIST={NO|YES}] 
[,PREFIX={NO|YES}] 


LIST={NOl| YES} 


NO 
specifies that only the UCB prolog is to be printed. 


YES 
specifies that the UCB prolog and the rest of the UCB 


are to be printed. 
PREFIX={NO]| YES} 


NO 





specifies that no prefix is to be printed. 


YES 
specifies that the prefix and main body of the UCB are 
to be printed. A DSECT statement is included if you 
specify PREFIX=YES. 


IEFJFCBN-~-MAPPING THE JFCB 


in the job file control block (JFCB). The macro does not 
include a DSECT statement. If you require one, code a DSECT 
statement before the macro statement. 


( This macro instruction defines the symbolic names of the fields 


The format is: 


IEFUFCBN| LLIST={NOIYES}1 


LIST={NOI| YES} 


NO 
specifies that only the JFCB prolog is to be printed. 


YES 


specifies that the JFCB prolog and the rest of the 
JFCB are to be printed. 


CVT—"MAPPING THE CVT 


This macro instruction defines the symbolic names of all fields 
in the communication vector table (CVT). 


The format is: 


[symbol] CVT [DSECT={£NO| YES} 1] 
[,LIST={NO|YES}] 
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DSECT={NO1 YES} 


NO 
specifies that you do not want a DSECT. 





VES | | | 
specifies that you want a DSECT. 


LIST={NO| YES} 


NO 
specifies that only the CVT prolog is to be printed. 
VES . 
specifies that the CVT prolog and the rest of the CVT 
are to he printed, 
OBTAINING I/O DEVICE CHARACTERISTICS 


Use the DEVTYPE macro instruction to request information 
relating to the characteristics of an I/0 device, and to cause 
this information to be placed into a specified area. (The 
results of a DEVTYPE macro instruction executed before a 
checkpoint is taken should not be considered valid after a 
checkpoint/restart occurs.) The IHADVA macro maps the data 
returned by the DEVTYPE macro. 


The topics that follow discuss the DEVTYPE macro, device 
characteristics, and particular output for particular devices. 


DEVTYPE MACRO SPECIFICATION 


The format is: 


[symbol] | DEVTYPE | ddloc-addrx or 


> a 
C,DEVTAB] 


[»>RPS] 





the name of an 8-byte field that contains the symbolic name 
of the DD statement to which the device is assigned. The 
name must be left justified in the 8-byte field, and must 
be followed by blanks if the name is less than eight 
characters. The doubleword need not be on a doubleword 
boundary. 


the name of an area into which the device information is to 
be placed. The area can be two, five, or six fullwords, 
depending on whether or not the DEVTAB and RPS operands are 
Specified. The area must be on a fullword boundary. 


DEVTAB 
This operand is only required for direct access devices. 
If DEVTAB is specified, the following number of words of 
information is placed in your area: 


e For direct access devices: 5 words 

e For non-direct access devices: 2 words 

If you do not code DEVTAB, one word of information is 
placed in your area if the reference is to a graphics or 


teleprocessing device; for any other type of device, two 
words of information are placed in your area. 





112 MVS/XA System-Data Administration 














RPS 
If RPS is specified, DEVTAB must also be specified. The 
RPS parameter causes one additional full word of RPS 
information to be included with the DEVTAB information. 


Note: Any reference for a DUMMY data set in the DEVTYPE macro 
instruction will cause eight bytes of zeros to be placed in the 
output area. Any reference to a SYSIN or SYSOUT data set causes 
X*'00000102' to be placed in word 0 and 32760 (X'00007FF8'") to be 
placed in word 1 in the output area. Any reference to a file 
allocated to a TSO terminal causes X'00000101' to be placed in 
word 0 and 32760 (X'O0007FF8&') to be placed in word 1 in the 
output area. 


| DEVICE CHARACTERISTICS INFORMATION 


The following information is placed into your area as a result 
of issuing a DEVTYPE macro: 


Word 0 | 
Describes the device as defined in the UCBTYP field of the 
UCB. For a complete description of this field, refer to 


Maximum block size. For direct access devices, this value 
is the smaller of either the maximum size of an nonkeyed 
block or the maximum block size allowed by the operating 
system; for magnetic tape devices, this value is the 
maximum block size allowed by the operating system. For 
all other devices, this value is the maximum block size 
accepted by the device. 


If DEVTAB is specified, the next three fullwords contain the 
following information about direct access devices: 


Word 2 


Bytes 0-1 The number of physical cylinders on the device, 
including alternates. 


Bytes 2-3 The number of tracks per cylinder. 


Note: Before you use bytes 2 and 3, read the 
description of word 4, byte l, bit 0Q. 


Word 5 


Bytes 0-1 Maximum track length. Note that for the IBM 
3375 and 3380 direct access devices, this value 
is not equal to the value in word 1 Cmaximum 
block size) as it is for other IBM direct 
access devices. 


aoe Before using bytes 2 and 3, read the description of word 


Byte 2 Block overhead, keyed block—the number of 
bytes required for gaps and check bits for each 
pe at block other than the last block on a 
rack. 


Byte 3 Block overhead-—the number of bytes required 
for gaps and check bits for a Keyed block that 
is the last block ona track. 


Bytes 2-3 Block overhead-—the number of bytes required 
for gaps and check bits for any Keyed block on 
a track including the last block. Use of this 
ipl es indicated by a l in bit 4, byte l of 
wor P 
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Byte 0 


Byte 1 


Bytes 2-3 


to 








Basic overhead-——the number of bytes required 
for the count field. Use of this form is 
indicated by a one in bit 3, byte 1 of word 4. 


Block overhead, block without key—the number 
of bytes to be subtracted from word 3, bytes 2 


or 3 or bytes 2 and 3, if a block is not Keyed. 


Tf bit 3, byte 1 of word 4 is 1, this byte 
contains the modulo factor for a modulo device. 


st 9 lt on, tne number of cylinders, as 
indicated in word 2, bytes 0 and 1 
are invalid. 

Bit l Reserved. 


Bits 2-3 If on, indicates a 3380 is attached 


to a 3880 Model 13 or 23 


Bit 3 If on, indicates a modulo device 
(3375, 3380). To calculate the 


number of data bytes required for a 
data block for a modulo device, see 


the device data in Data 


Bit 4 If on, bytes 2 and 3 of word 3 


contain a halfword giving the block 


overhead for any block ona track, 
including the last block. 


Bits 5-6 Reserved. 

Bit 7 If on, a tolerance factor must be 
applied to all blocks except the 
last block on the track. 


Tolerance factor-~——this factor is used to 


calculate the effective length of a block. The 


calculation should be performed as follows: 


step ) add the block's key length to the 
block's data length. 


step 2 test bit 7 of byte 1 of word 4. If 
bit 7 is 0, perform step 3. If bit 


7 is l, multiply the sum computed 
in step 1 by the tolerance factor. 
Shift the result of the 


multiplication 9 bits to the right. 


Step 3 add the appropriate block overhead 
— to the value obtained above. 


If bit 3, byte 1 of word 4 is 1l, bytes 2 and 3 


contain the overhead for the data or key field. 


If DEVTAB and RPS are specified, 


the following information: 


Word 5 
Bytes 0-1 
Byte 2 
Byte 3 


RO overhead for sector calculations 
Number of sectors for the device 


Number of data sectors for the device 
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the next fullword contains 


oa 
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WS 


a, 
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Figure 24 shows the output for each device type that results 
from issuing the DEVTYPE macro. 


( | RETURN CODES FROM THE DEVTYPE MACRO 





Control is returned to your program at the next executable 
instruction following the DEVTYPE macro instruction. Register 
15 contains a return code from the DEVTYPE macro. The return 
codes and their meanings are as follows: 


Code Meaning 

00CX*'00"') Indicates that the information concerning the ddname 
you specified has been successfully moved to your work 
area. 


04(€X'04") Indicates that the ddname you specified was not found. 


Maximum 
Record Size RPS (Word 5, 


(Word 1, in DEVTAB (Words 2, 3> and in 
Decimal ) 4, in Hexadecimal) Hexadecimal ) 


Not Applicable Not Applicable 
Not Applicable Not Applicable 
Not Applicable Not Applicable 


Not Applicable Not Applicable 
Not Applicable Not Applicable 


Not Applicable Not Applicable 


Not Applicable Not Applicable 


Not Applicable Not Applicable 


Not Applicable Not Applicable 
Not Applicable Not Applicable 





Devicel,@ 

2540 Reader 

2540 Reader w/CI 
2540 Punch 

2540 Punch w/CI 
2501 Reader 

2501 Reader w/CI 


3890 Document | 
Processor 


3505 Reader 
3505 Reader w/CI 1 
3525 Punch i 
3525 Punch w/CI ! 
1403 Printer 1205 Not Applicable Not Applicable 









—_ 
® J 


Not Applicable Not Applicable 


Le.) 
3 


1403 w/UCS 1202 Not Applicable 
3203 Model 5 Printer | 132 _ Not Applicable 
3211 Printer 1323 | Not Applicable —_—si|s- Not Applicable 
3262 Model 5 Printer | 132 Not Applicable 
4245 Printer Not Applicable 
4248 Printer 1324 Not Applicable 


3800 Printing 136° Not Applicable Not Applicable 


Subsystem 
32760 Not Applicable Not Applicable 


3400 (9-track, p.e.) 
3400 (€9-track, d.d.) 32760 Not Applicable Not Applicable 


Output from DEVTYPE Macro 


fwd 
GN 


‘ 
“Tl 
ja: 
Fe] 
c 
> | 
1) 
nN 
iN 
ta 
“0 
o) 
“5 
ce 
jt 
oe) 
oh 
a] 
Na 
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Maximum 
Record Size RPS (Word 5, 


| (Word 1, in | DEVTAB (Words 2, 3, and in ; 
Devicel,2 Decimal ) 4, in Hexadecimal) Hexadecimal) 





3400 (€7-track) 32760 Not Applicable 7 Not Applicable 
3480 (18-track) | 32760 | Not Applicable Not Applicable 


2305 Model 2 14660. 006000083A0A01215B080200 0140B4B1 
Fixed-Head Storage 


3330/3333 Disk 13030 019B0013336DBFBF38000200 QOGED807C 
Storage 3 

ope hh MSS Virtual 13030 019B0013336DBFBF38000200 OOED&07C 
olume 


3330 Model 11 Cor 13030 O32FO0013336DBFBF38000200 | OOED807C 
3333 Model 11) Disk 
Storage 





3340 Disk Storage 8368 015D000C2157F2F24B000200 0125403D 
€35 megabytes) | 


3340/3344 Disk 8368 0230001E4B36010B52080200 0125403D 
Storage (70 
megabytes) 





3350 Disk Storage | 19069 0230001E4B56010B52080200 0185807B 
3375 Disk Storage 32760 OS3BFO00C8CADDDE02Z01000BF 0340C4BB 


3380 Models A04, 32760 0376000FBB6001002010010B OGEODED6 
AAG, and B04 Disk | 
| Storage | 





3380 Models A0G, 32760 0376000FBB6001002030010B OGEODED6 
AAG, and B04 Disk 

Storage Cattached to : 

or Model 13 or 

23) 


2250 Model 3 Display Po Not Applicable Not Applicable 
ni 


Figure 24 (Part 2 of 2). Output from DEVTYPE Macro 










Notes to Figure 24: 


i CI-—-card image feature; d.c.—~-data conversion; d.d.—dual 
. pst p.e.—phase encoding; UCS-—~universal character set; 
w/——-with. 


2 Device codes are presented in Debugging Handbook. 
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3 Although certain models can have a larger line size, the 
minimum line size is assumed. 


4 The IBM 4248 Printer returns 132 characters even if the 168 
Print Position Feature is installed on the device. 


5 The IBM 3800 Printing Subsystem can print 136 characters per 
line at 10-pitch, 163 characters per line at 12-pitch, and 
204 characters per line at 15-pitch. The machine default is 
136 characters per line at 10-pitch. 





To accomplish the functions that are performed as a result of an 
OPEN macro instruction, the open routine requires access to 
information that you have supplied ina data definition (DD) 
statement. This information is stored by the system ina job 
file control block CJFCB). 


In certain applications, you may find it necessary to modify the 
contents of a JFCB before issuing an OPEN macro instruction. 

For example, suppose you are adding records to the end of a 
sequential data set. You might want to add a secondary 
allocation quantity to allow the existing data set to be 
extended when the space currently allocated is exhausted. To 
assist you, the system provides the RDJFCB macro instruction. 
This macro instruction causes a specified JFCB to be moved from 
the scheduler work area (CSWA), where it is stored, to an area 
specified in an exit list. (The use of the RDJFCB macro 
instruction with an exit list is shown under "Example™ on 

page 118. The symbolic names and field descriptions of the JFCB 
are contained in Debugging Handbook.) When you subsequently 
issue the OPEN macro instruction, you must indicate, by 
specifying the TYPE=J operand, that you want to open the data 
set using the JFCB in the area you specified. 


Caution: If you set the bit JFCNWRIT in the field JFCBTSDM to 1 
before you issue the OPEN macro instruction, the JFCB is not 
written back to the SWA at the conclusion of open processing. 
OPEN TYPE=J normally moves your program's modified copy of the 
JFCB to the SWA (Scheduler Work Area), replacing the system 
copy. To ensure that this move is done, your program must set 
bit zero C0) of the JFCBMASK+4 field to 1. The JFCBMASK format 
1s shown in the Internal Data Areas section of / se/ 

. Lf the user JFCB, which the system used to open the data 
set, is not written back to SWA CJFCNWRIT set on), then errors 
may occur during EOV or close processing. 


Some of the modifications that are commonly made to the JFCB 
include: 


e Moving the creation and expiration date fields of the DSCB 
eS has JFCB (see "Using RDJFCB for MSS Virtual Volumes" 
elow). 


e Moving the secondary allocation quantity from the DSCB into 
the JFCB (see "Using RDJFCB for MSS Virtual Volumes" below). 


e Moving the DCB fields from the DSCB into the JFCB. 


® Adding volume serial numbers to the JFCB (see "Using RDJFCB 
for MSS Virtual Volumes™ and "RDJFCB Security™ below). 


Volume serial numbers in excess of five are written to the 
JFCBX Cextension) located in the SWA. The JFCBX cannot be 
modified by user programs. 

e Modifying the data set sequence number field in the JFCB. 


e Modifying the number-of-volumes field in the JFCB (see 
"Using RDJFCB for MSS Virtual Volumes" below). 
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@ Setting bit JFCDQDSP in field JFCBFLG3 to invoke the tape 
volume DEQ at demount facility (see "DEQ at Demount Facility 
for Tape Volumes," below)... | 


e Modifying the JFCRBIDO field in the JFCB to cause high-speed 
positioning to a specific data block on a 3480 tape volume. 


| RDJFCB—READ A JOB FILE CONTROL BLOCK 


The RDJFCB macro instruction causes a job file control block 
CJFCB) to be moved from the SWA (scheduler work area) into an 
area of your choice as identified via the EXLST parameter of the 
DCB macro for each data control block specified. 


[symbol] RDJFCB (dcb-address 
»ECCoptions)],...) 


_ r tions 
(same as the dcbaddress, optionl, and option2 operands of 
the OPEN macro instruction, as shown in Data 

n: Macro fe) : 


Although the option operands are not meaningful during the 
execution of the RDJFCB macro instruction, these operands 
can appear in the list form of either the RDJFCB or OPEN 
macro instruction to generate identical parameter lists, 
which can be referred to with the execute form of either 
macro instruction. 


Example: In Figure 25 on page 119, the macro instruction at EXl 


creates a parameter list for two data control blocks: INVEN and 
MASTER. In creating the list, both data control blocks are 
assumed to be opened for input; option2 for both blocks is 
assumed to be DISP. The macro instruction at EX2 moves the | 
system-created JFCBs for INVEN and MASTER from the SWA into the 
area you specified, thus making the JFCBs available to your 
problem program for modification. The macro instruction at EX3 
modifies the parameter list entry for the data control block 
named INVEN and indicates, through the TYPE=J operand, that the 
problem program is supplying the JFCBs for system use. 
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EX1 RDJFCB CINVEN, ,MASTER),MF=L 
EX2 RDJFCB MF=(E,EX1) 
EX3 OPEN (, (RDBACK, LEAVE)), TYPE=J,MF=CE, EX1) 
INVEN DCB EXLST=LSTA,... 
MASTER DCB EXLST=LSTB>... 
LSTA DS OF 
DC X'07" 
DC AL3( JFCBAREA) 
JFCBAREA DS 0F,176C 


LSTB DS OF 
Figure 25. Sample Code Using RDJFCB Macro 


Multiple data control block addresses and associated options may 
be specified in the RDJFCB macro instruction. This facility 
Leta rea possible to read several job file control blocks in 
paralle 


An exit list address must be provided in each data control block 
specified by an RDJFCB macro instruction. Each exit list must 
contain an active entry that specifies the virtual storage 
address of the area into which a JFCB is to be placed. A full 
discussion of the exit list and its use 1s contained in 

stra Guide. The format of the job file control block 
exit list entry is as follows: 


Types of Hexadecimal 
Exit List Code (High- Contents of Exit List Entry 
Entry Order Byte) (Low-Order Bytes) 


Address of a 176-byte area to be 
provided if the RDJFCB or OPEN 
CTYPE=J) macro instruction is 
used. This area must begin on a 
fullword boundary and must be 
located within the user's 
region. Also, users running in 
31-bit addressing mode must 
ensure that this area is located 
below 16-megabyte virtual. 





The virtual storage area into which the JFCB is read must be at 
least 176 bytes long. 


The data control block may be open or closed when this macro 
instruction 1s executed. 
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If the JFCB is read successfully for all DCBs in the parameter 

list, a return code of 0 is placed in register 15. If the JFCB 

is not read for any of the DCBs because the DDNAME is blank, or f 
a DD statement is not provided, a return code of 4 is placed in w/ 
register 15. 


Warning: The following errors cause the results indicated: 


A DD statement has not been A return code of 4 is 
provided. placed in register 15. 


DDNAME field in DCB is A write-to-programmer is 


blank, issued, the request for 
this DCB is ignored, and a 
return code of 4 is placed 
in register 15. 





A virtual storage address Abnormal termination of 
has not been provided. task. 


Note that, if you want to open a VTOC data set to change its 
contents (that is, open it for OUTPUT, OUTIN, INOUT, UPDAT, 
OUTINX, or EXTEND), your program must be authorized under the 
Authorized Program Facility CAPF). APF provides security and 
integrity for your data sets and programs. Details on how you 


authorize your program are provided in System Programming 
Library: Supervisor Services and Macro Instructions. 


Cc Cc 


If the RDJFCB routine fails while processing a DCB associated 
with your RDJFCB request, your task is abnormally terminated. 


None of the options available through the DCB ABEND exit, as a 
described in Data Administration Guide, is available when a —_— 
RDJFCB macro instruction is issued. we 


When using concatenated data sets, the RDJFCB routine modifies 
only the first JFCB. 


USING RDJFCB FOR MSS VIRTUAL VOLUMES: Care must be taken in 
rpg RDJFCB if the data set resides on MSS virtual volumes such 
at: 


e The expiration date added does not conflict with other 
volumes within the specified MSVGP. 


e The secondary allocation quantity should be in cylinder 
increments and be a multiple or submultiple of the primary 
allocation quantity to avoid fragmentation. 


e The number of volumes must not exceed the number available 
in the specified MSVGP. 


e Any volume serial numbers added to the JFCB should exist in 
the MSVGP. 


RDJFCB SECURITY: The volume serial numbers specified in the 
user-supplied JFCB will be compared with the volume serial 
numbers in the system JFCB located in the SWA. Each different 
volume serial number will be enqueued exclusively. The volumes 
will stay enqueued until the job step terminates, because the 
close routines will not dequeue the volumes. If the job step 
already has the volume open, OPEN TYPE=J will continue. If the 
volume is enqueued by another job step, a 413 abend will occur 
with a return code of 04. 


Some JFCB modifications can compromise the security of existing 
password-protected data sets. The following modifications are 
specifically not allowed, unless the program making the 
modifications is authorized or can supply the password: 
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e Changing the disposition of a password-protected data set 
from OLD or MOD to NEW. 


e Changing the data set name of one or more of the volume 
serial numbers when the disposition is NEW. 


® Changing the label processing specifications to bypass label 
processing. 


Note: An authorized program is one that is either in supervisor 
state, executing in one of the system protection Keys (keys 0 
through 7), or authorized under the Authorized Program Facility. 


RDJFCB USE BY AUTHORIZED PROGRAMS: If you change the data set 
name in the JFCB, you should do a system enqueue on the major 
name of "SYSDSN" for the substituted data set name. To use the 
correct interface with other system functions (for example, 
partial release), the ENQUEVUE macro should include the TCB of 
the initiator and the length of the data set name (with no 
trailing blanks). When you complete processing of the data set, 
you should use the DEQ macro to release the resources. 


DEQ AT DEMOUNT FACILITY FOR TAPE VOLUMES 





_spemerrmepesettmnnesmaamn ne oy one tty Sarat emda udneenape asarmecta tneyhy tanefitchled PAE INE SNES PCOS SUE De IOUNM IRE TEASE LAER: AG HORE PI 


This facility 1s intended to be used by long-running programs 
that create an indefinitely long tape data set (such as a log 
tape). Use of this facility by such a program permits the 
processed volumes to be allocated to another job for processing 
Csuch as data reduction). This processing is otherwise 
prohibited unless the indefinitely long data set is closed and 
dynamically unallocated. 


You may invoke this facility only through the RDJFCB/OPEN TYPE=J 
interface by setting bit JFCDQDSP (bit 0) in field JFCBFLG3 
Coffset 163 or X'A3') to 1. The volume serial of the tape is 
dequeued when the volume is demounted by OPEN or EOV with 
message IEC502E when all the following conditions are present: 


@ The tape volume is verified for use by OPEN or EOV. 
e JFCDQDSP is set to l. 


e The program is APF authorized (protect key and 
supervisor/problem state are not relevant). 


e The tape volume is to be immediately processed for output. 
That is, either OPEN verifies the volume and the OPEN option 
is OUTPUT, OUTIN, or OUTINX; or EOV verifies the volume and 
the DCB is opened for OUTPUT, OUTIN, INOUT, or EXTEND, and 
the last operation against the data set was an output 
operation (DCBOFLWR is set to 1) 


Note that, in order for EOQV to find JFCDQDSP set to l, the 
program must not inhibit the rewrite of the JFCB by setting bit 
G of JFCBTSDM to l. 


The tape volume 1s considered verified after file protect, label 
type, and density conflicts have been resolved. The volume is 
dequeued when demounted after this verification, even if further 
into OPEN or EQOV processing the volume is rejected because of 
expiration date, security protection, checkpoint data set 
protection, or an I/0 error. 


When the volume serial is dequeued, the volume becomes available 
for allocation to another job. However, because the volume DEQ 
1s performed without unallocating the volume, care must be 
exercised both by the authorized program and the installation to 
prevent misuse of the DEQ at demount facility. A discussion of 
such misuse follows. 


1. The authorized program must not close and reopen the data 


set using the tape volume DEQ at demount facility. If it 
does, one of the following can occur: 
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a. The dequeued. volume may be mounted and in use by another 
job. When the volume is requested for mounting, for the 
authorized program, the operator is unable to satisfy 
the mount. Therefore, the operator must either cancel 
the requesting job, cancel the job using the volume, 
wait for the requesting job to time out, or wait for the 
job using the volume to terminate. | a 


b. The dequeued volume may be allocated to another job but 
not yet in use. The operator mounts the volume to 
satisfy the mount request of the authorized job. When 
the volume is requested for mounting by the other job, 
the operator is unable to satisfy the mount request, and 
is faced with the same choices as in a, above. 


Cc. The deaueued volume may nat yet be allocated tse ansther 


SE 
Oe ee ee eo) SW CUI ets 


job and the volume is mounted to satisfy the mount 
request of the authorized job. Another job may allocate 
the volume and, when the volume is requested for 
mounting, the situation is the same as in b, above. 


It is the responsibility of the installation that permits a 
program to run with APF authorization to ensure that it does 
eee and reopen a data. set using the DEQ at demount 
acility. 


2. Care should be exercised when an authorized program uses the 
- DEQ at demount facility Cdata set 1) but processes another 

tape data set (data set 2). Assume the same volume serial 
numbers have been coded in the DD statements for data set 1 
and data set 2. As the volumes of data set 1 are demounted, 
they are dequeued even though those volumes may yet be 
requested for data set 2. All the problems explained in a, 
b, and c in1, above, may occur as data set 2 and ancther 
job contend for a dequeued volume. 


This problem should not occur, given the intended use of the 
DEQ at demount facility. That is, a long-running 
application creating an indefinitely long tape data set. 
This type of application is not normally invoked through 
batch execution with user-written DD statements. 


3. After a volume has been demounted and dequeued because of 
the DEQ at demount facility, the volume is not automatically 
rejected by the control program when mounted in response to 
a specific or nonspecific mount request. Without the use of 
the facility, the control program can recognize (by the ENQ) 
that the volume is in use, and reject the volume. 

Therefore, operations procedures, in effect to prevent 
incorrect volumes from being mounted, should be reviewed in 
the light of reduced control program protection from such 
errors when the DEQ at demount facility is used. 
Specifically, if a volume is remounted for an authorized 
program and the volume had been used previously by that 
authorized program, duplicate volume serial numbers will 
exist in the JFCB, and the control program will be unable to 
release the volume during EOV processing. 


G. Checkpoint/restart considerations are discussed in 
i / 


OPEN-~INITIALIZE DATA CONTROL BLOCK FOR PROCESSING THE JFCB 


The OPEN macro instruction initializes one or more data control 
blocks so that their associated data sets can be processed. 


A full explanation of the operands of the OPEN macro 
instruction, sae rit for the TYPE=J option, is contained in Data 

ce. The TYPE=J option, 
because it is "eee" in conjunction with modifying a JFCB, should 
be used only by the system programmer or only under the system 
programmer's supervision. 
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TYPE=J 
specifies that, for each data control block referred to, 
you have supplied a job file control block (CJFCB) to be 
used during initialization. A JFCB is an internal 
representation of information ina DD statement. 


During initialization of a data control block, its 
associated JFCB may be modified with information from the 
data control block or an existing data set label or with 
system control information. 


The system always creates a job file control block for each 
DD control statement. The job file control block is placed 
in the SWA (scheduler work area). Its position, in 
relation to other JFCBs created for the same job step, is 
noted ina table in virtual storage. 


When the TYPE=J operand is specified, you must also supply 
a DD statement. However, the amount of information given in 
the DD statement is at your discretion, because you can 
modify many fields of the system-created job file control 
block. If you specify DUMMY on your DD statement, the open 
routine will ignore the JFCB DSNAME and open the data set 
as dummy. (See Figure 25 on page 119 for a coding example 
that modifies a system-created JFCB.) 


Note: The DD statement must specify at least: 


e Device allocation Crefer to JCL for methods of preventing 
share status) 


— e A _ddname corresponding to the associated data control block 
DCBDDNAM field 


| HIGH-SPEED POSITIONING FOR THE IBM 3480 MAGNETIC TAPE SUBSYSTEM 


Fast positioning for 3480 tape drives is available when opening 
a tape data set on an IBM standard-labeled tape for EXTEND 
COUTINX, EXTEND, or DISP=MOD). To invoke high-speed positioning 
your program must modify certain fields in the JFCB and use OPEN 
TYPE=J to open the data set. 


The following procedure should be used to modify the JFCB: 


l. Issue RDJFCB to have the system move the JFCB into your work 
area. 


2. Set the JFCPOSID flag in the JFCBFLG3 flag byte to indicate 
that you are providing a Block ID for a high-speed search. 


3. Move the Block ID into the JFCRBIDO field of the JFCB. 
(Specify the Block ID of the tape mark immediately following 
the last block of user data in the data set being opened.) 


4. Issue OPEN TYPE=J with the modified JFCB. 


Once the tape is positioned, OPEN processes the trailer labels 
for the data set being extended. 


If you set the JFCPOSID flag off, OPEN positions the volume 
ell ig as though the high-speed positioning feature were not 
active. 


If you set the JFCPOSID flag on, but do not provide a block ID 
in the JFCRBIDO field, OPEN positions the volume normally. OPEN 
then moves the block ID of the first header label record into 
the JFCRBIDO field. 
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If you set the JFCPOSID flag on, but the block ID you provide in 
the JFCRBIDO field does not exist on the tape, OPEN processing 
sbeereee OPEN issues error message TECI4/1 to indicate this 
condition. 


If the JFCPOSID flag oe on anne CLOSE processing, CLOSE 
inserts the block ID for the first header label record of the 


next data set Cwhich may not exist) into the JFCRBIDO field. 


Therefore, if you deallocate the 3480 device and want to use the 
current block ID for subsequent processing, you must save the 
block ID before you CLOSE the data set. 


Notes: 
Ll. If you specify dynamic deallocation Cwith SVC 99, gs 


an tha nn setateamant, ar tha FREE option an tha CLOS 


~~ Sw tee owe s eh tee wae Wri € wite CLOSE 


then the block ID for the next data set will not be 
available to your program. This is because dynamic 
deallocation frees the JFCB. 


CLOSE 


om 
om 
“a 
1c e 


2. When using high-speed positioning, specify the data set 
sequence number normally, either explicitly by 
LABEL=Cseqno, SL) on the DD statement, or by default. 


R ALIDATING THE DATA EXTENT BLOCK 

Protecting one user's data from inadvertent or malicious access 
by an unauthorized user depends on protection of the data extent 
block (DEB). The DEB is a critical control block because it 
contains information about the device a data set 1S mounted on, 
and describes the location of data sets on direct access device 
storage volumes. The DEB also contains the address of the 
appendage vector table (CAVT). Using the AVT, an unauthorized 
user can modify the AVT to give control to a routine in 
supervisor state to read from and write to data sets to which 
access would otherwise be denied. 


To guarantee protection of the DEB, the DEBCHK macro mneceueon 
is provided. The DEBCHK macro instruction can be found in 
SYSI1.MACLIB. The DEBCHK macro is issued by several components 
of the system control program. For example: 


® The open access method executors issue the macro to add the 
address of a DEB they have built to a list of valid 
addresses called the DEB table. The DEB validity-~checking 
routine builds and maintains a DEB table for each job step. 


e The EXCP processor uses the macro to verify that the DEB 
passed with each EXCP request is in the DEB table. 


@ The close component issues the macro to remove a DEB from 
the DEB table. 


If you code a routine that builds a DEB, you must add the 
address of the DEB you built to the DEB table. If you code a 
routine that depends on the validity of a DEB that is passed to 
your routine, you should verify that the DEB passed to your 
routine has a valid entry in the DEB table and points to your 
DCB or access method control block CACB). Use the TYPE=ADD and 
the TYPE=VERIFY operands of the macro, respectively. 


To prevent an asynchronous routine from changing or deleting, or 
assigning a new DEB to a DCB, you must hold the local lock. In 
this case, you must use the branch entry to the DEBCHK verify 
routine. 


Additional details about the functions provided by the DEB 
validity- checking routine and about the contents of the DEB 
table are available in / / ; 


The DEBCHK macro instruction provides four functions: 


124 MVS/XA System-Data Administration 


ed 




















@ Adds the address of a DEB to the DEB table, which is located 
in protected storage. The DEB table contains the address of 
every user DEB associated with a given job step. Every 

( system control program component that builds a user DEB must 
be | add the address of that DEB to a DEB table. 


e Verifies that the DEB table associated with a given job step 
contains the address of.a valid DEB and that the DEB points 
to the DCB Cor ACB). Any system control program component 
or problem program can use this function to verify that a 
DEB is valid 


e Deletes the address of a DEB from the DEB table. Any 
program that deletes a user DEB must, before it deletes the 
DEB, issue a DEBCHK macro with a TYPE=DELETE operand to 
delete the address of the DEB from the DEB table. If the 
DEB. validity~checking routine encounters an error while 
deleting the address from the DEB table, the job step is 
abnormally terminated. 


e Deletes the address of a DEB from the DEB table in the same 
way as the preceding function, except that, instead of 
terminating the job step, this function merely returns an 
error code in register 15. This function 1s provided to 
prevent recurring abnormal termination. The format of the 
DEBCHK and a description of the operands follow: 


DEBCHK~"MACRO SPECIFICATION 


[symbol] DEBCHK cbhaddr 
TYPE={VERIFY | ADD | DELETE | PURGE} ] 
AM={antype]l (amaddr) | (Camreq))}1 
BRANCH ENOIVES? 1 
address] 


» KEYADDR=address] 
» SAVREG=regq] 
MF=L] 





[, 
[, 
a4 » TCBADDR= 
[ 
[> 


chaddr 


for BRANCH=NO 
RX-type address, (2-12), or (1) 


A control block address passed to the DEBCHK routine. This 
operand is ignored if MF=L is coded. For verify, add, and 
delete requests, cbaddr is the address of a DCB or ACB that 
points to the DEB whose address is either verified to be in 
the DEB table, added to the DEB table, or deleted from the 
DEB table. For the purge function, cbaddr is the address 
of the DEB whose pointer is to be purged from the table: 

No reference is made to the DCB or ACB. 


Note: A spooled DCB's DEB does not point back to the DCB, 
but to the speoled ACB; in this case, the DEBCHK should be 
issued against the ACB. 


for BRANCH=YES 
The A-type address of a 4-byte field, or a register 
C1) or €3-12), that points to the DCB or ACB 
containing the DEB to be verified. 


TYPE={VERIFY | ADD | DELETE | PURGE} 
indicates the function to be performed. If MF=L is coded, 
TYPE 1s ignored. The functions are: 


VERIFY 
This function is assumed if the TYPE operand is not 
coded. The control program checks the DEB table to 
determine whether the DEB pointer is in the table at 
the location indicated by the DEBTBLOF field of the 
DEB. The DEB is also checked to verify that DEBDCBAD 
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points to the DCB Cor ACB) passed to DEBCHK. The 
DEBAMTYP field in the DEB is compared to the AM 
operand value, if given. The two must be equal. 
TYPE=VERIFY may be issued in either supervisor or 
problem state. 





ADD ) 

The DEB and the DCB Cor ACB) must point to each other 

before the DEB address can be added to the DEB table. 

Before the DEB pointer can be added to the table, the 

DEB itself must be queued on the current TCB DEB chain 
Cthe TCBDEB field contains the address of the first 

| DEB in the chain). The DEB address is added to the 

| DEB table at some offset into the table. That offset 

| | value is placed in the DEBTBLOF field of the DEB, and 


mbm hi nw NRODAM TVD 
the access methed tyre is inserted TLS the DEBAMIYE 


| field of the DEB. A zero is placed in the DEBAMTYP 
| field if the AM operand is not coded. TYPE=ADD can be 
issued only in supervisor state. 


| DELETE 

| The DEB and the DCB Cor ACB) must point to each other 
before the DEB address can be deleted from the DEB 
Src TYPE=DELETE can be issued only in supervisor 
state. 


PURGE 
The DEB pointer is removed from the DEB table without 
checking the DCB Cor ACB). TYPE=PURGE can be issued 
only in supervisor state. 





AM 
specifies an access method value. Each value corresponds 
to a particular access method type (note that BPAM and SAM 
have the same values): 





Type Value —_ 
Cw 
TCAMAP (X'84") oe 
SUBSYS (X'81") 
ISAM (X'80") 
BDAM (X'G0") 
SAM (X'208) 
BPAM (X'20") 
TAM (X?10") 
GAM (X108") 
TCAM (X106") 
! EXCP (Xt 02°) 
| VSAM (Xt 01") 
: NONE CX" 00") 


The operand can be coded in one of the following three 
ways, only the first of which 1s valid for the list form 
CMF=L) of the instruction. 


amtvpe | 
refers to the access method: ISAM, BDAM, SAM, BPAM, 
TAM Cwhich refers to BTAM only), GAM, TCAM, EXCP, or 
VSAM. TCAMAP identifies a TCAM application-program 
DEB. SUBSYS identifies a subsystem of the operating 
system, such as a job entry subsystem. NONE indicates 
that no access method or subsystem is specified. 


Camaddr) 
is the RS-type address of the access method value. 
This format may not be coded when MF=L is used. 





(Camreg)) 
is one of the general registers 1 through 14 that 
contains the access method value in its low-order byte 
(bit positions 24 through 31). The high-order bytes 
are not inspected. This form may not be used when 
MF=L is coded. 
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The use of amaddr and amreg should be restricted to those 
cases where the access method value has been generated 
previously by the MF=L form of DEBCHK. If MF=L is not 
occa the significance of the AM operand depends upon the 


If TYPE is ADD and AM is specified, the access method value 
1s inserted in the DEBAMTYP field of the DEB, and all 
subsequent DEBCHK macros referring to this DEB must either 
specify the same AM or omit the operand. When the AM 
operand is omitted for TYPE=ADD, a null value (0) is placed 
in the DEB and all subsequent DEBCHK macros must omit the 
AM operand. 


If AM is specified when the TYPE is PURGE, DELETE, or 
VERIFY, the access method value is compared to the value in 
the DEBAMTYP field of the DEB. If AM is omitted, no 
comparison is made. 


BRANCH={NO I YES} 
specifies whether you want to use the branch entry to the 
DEBCHK verify routines. 


NO 
specifies branch entry is not to be used. The 
operands SAVREG, TCBADDR, and KEYADDR are ignored. 


YES 
specifies the branch entry is to be used. TYPE=VERIFY 
must be implicitly or explicitly specified. The 
operands TCBADDR and KEYADDR are required. AM and MF 
are ignored. Notes for BRANCH=YES: 


e Registers 1, 2, 10, 11, 14, and 15 must not be 
used for SAVREG=. 


e Registers 1, 2, 10, 11, 14, 15, and the register 
specified for SAVREG= must not be used for chaddr, 
TCBADDR=, or KEYADDR=. 


e The contents of registers 10, 11, and 14 are 
unpredictable on completion. Also, if you do not 
specify SAVREG=, the contents of register 2 are 
unpredictable. 


e At completion time, register 1] contains the 
address of the DEB, and register 15 contains 
either 0, 4%, or 16 (see below for codes and their 
meanings). 


TCBADDR=address—A-type address or (3-12) 
specifies the location or register containing the address 
of the TCB to be used by the DEBCHK verify routine. Use 
this operand only when BRANCH=YES. 


KEYADDR=address—A-type address or (3-12) 
specifies the location, or a register pointing to the 
location of a field containing the Key to be used when 


accessing the DCB Cor ACB). Use this operand only when 
BRANCH=YES. 


SAVREG=req | 
specifies the register in which register 2 is to be saved. 
Use this operand only when BRANCH=YES. 


indicates the list form of the DEBCHK macro instruction. 
When MF=L is coded, a parameter list is built consisting. of 
the access method value that corresponds to the AM keyword. 
This value may be referenced by name in another DEBCHK 
macro by coding AM=(Camaddr), or it may be inserted into the 
low-order byte of a register before issuing another DEBCHK 
macro by coding AM=(Camreg)). 
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Return Codes from the DEBCHK Macro 


If the DEBCHK routine completes successfully, register 15 will 
be set to 0 and register 1] will contain the address of the DEB 
when control is returned to your program. Otherwise, register 
15 will contain one of the following decimal codes: 





Code Meaning 


O40X'04"') Either Ca) the DEB table associated with the job step 
does not exist; or (b) the DEBTBLOF field of the DEB 
was set to zero or a negative number, or was larger 
than the DEB table; or (c) register 1 did not contain 
the same address as the DEB table entry. 


O8CX'08"') An invalid TYPE was srecified. (The DEBCHK routine 
was entered by a branch, not by the macro.) 


12¢X'0C*') Your program was not. authorized and TYPE was not ) 
VERIFY. , 


16CX'10') DEBDCBAD did not contain the address of the DCB Cor 
ACB) that was passed to the DEBCHK routine. 


200CX'14") ee value does not. equal the value in the DEBAMTYP 
1eld. 


24(X'18") The DEB is not on the DEB chain and TYPE=ADD was 
specified. 


28CX'1C') TYPE=ADD was specified for a DEB that was already 
entered in the DEB table. 


32€X'20') The DEB table exceeded the maximum size (32760 bytes) 
and TYPE=ADD. 


cr 





The system's purge routines, guided by a parameter list you pass 
them, perform either a halt or a quiesce operation. Ina halt 
operation, the purge routines stop the processing of specified 
I/0 requests that were initiated with an EXCP macro instruction. 
In a quiesce operation, the purge routines: 


° Allow the completion of I/0 requests that were initiated 
with an EXCP macro instruction and have been passed to the 
I/0 supervisor for execution 


e Stop the processing of those requests that have not as yet 
been passed to the I/0 supervisor, but save the IOBs of the 
requests so that they can be reprocessed Crestored) later. 


The system's restore routines make it possible to reprocess 170 
requests that are quiesced., CNote: Not covered here is the 
purge and restore processing that takes in I/O requests not | 
initiated by an EXCP macro instruction. If you want to learn 

the full scope of purge and restore processing, see the I/0 

supervisor logic section of System Logic Library, Volume 8.) 


You can give control to the purge and restore routines in one of 
two ways: (C1) by loading register l with the address of the 
parameter list and issuing specific SVC instructions or (2) by 
issuing the PURGE and RESTORE macro instructions. If your 
installation requires the use of macro instructions, you must 
add the macro definitions to the macro library (SYS1.MACLIB) or 
place them in a partitioned data set and concatenate this data 
set to the macro library. The macro definitions, JCL, and 
utility statements needed to add the macros to your macro 
library are presented in Figure 26 on page 129, and Figure 27 on 
page 129. Whether you issue the macro instructions or the SVC 
instructions, you must first build a parameter list. The SVC 
instructions are SVC 16 for PURGE and SVC 17 for RESTORE. 
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PURGE Macro Definition 





MACRO 
&NAME PURGE &LIST 
AIF C'&LIST® EQ "*).E1 
&NAME IHBINNRA &LIST LOAD REG 1 
SVC 16 
MEXIT 
~El cena 01,147 LIST ADDR MISSING 


Control Statements Required 


//jobname JOB {parameter} 

//stepname EXEC PGM=IEBUPDTE, PARM=NEW 
ZASYSPRINT DD SYSOUT=A 

//SYSUT2 ~~ DD DSNAME=SYS1.MACLIB, DISP=OLD 
S/SYSIN DD ¥ 

.“ ADD NAME=PURGE,LIST=ALL 


PURGE macro definition 


.4 ENDUP 
7% 


Figure 26. Macro Definition, JCL, and Utility Statements for 
Adding PURGE Macro to the System Macro Library 


RESTORE Macro Definition 


MACRO 
&NAME RESTORE &LIST 
AIF CfSLIST' EQ °°). EL 
&NAME IHBINNRA &LIST LOAD REG 1 
oVC 17 ISSUE SVC FOR RESTORE 
MEXIT 
sEL ert el 01,150 LIST ADDR MISSING 


Control Statements Required 


//jobname JOB {parameters} 

//stepname EXEC PGM=IEBUPDTE,PARM=NEW 
/7SYSPRINT DD SYSOUT=A 

//SYSUT2 DD DSNAME=SYS1 .MACLIB, DISP=OLD 
S“SYSIN DD DATA 

.f ADD NAME=RESTORE,LIST=ALL 


RESTORE macro definition 


-f ENDUP 
/%® 


Figure 27. Macro Definition, JCL, and Utility Statements for 
Adding RESTORE Macro to the System Macro Library 
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PURGE“"HALT OR FINISH I/0-REQUEST PROCESSING 


The macro instruction used to call the purge routines is coded 
as follows: ph 


[symbol] Parameter-list 


j RX-type address, (2-12) or (1) 
address of a parameter list, 12 or 16 bytes long, that you 
have built on a fullword boundary in your storage. The 
parameter list address can be specified as an RX-type 
constant or in registers 2 through 12, or l. 


The format and contents of the parameter list are as follows: 
Byte Contents | 


0 A byte in which you specify what the purge routines 
, will do. These are the bit settings and their 
meanings: 


0 ne ee ai Purge I/0 requests to a single data set. 


Owe selene Either purge I/0 requests associated with 
a TCB or address space, or purge I/0 
requests to more than one data set. 


cle ae. giseters Post ECBs associated with purged I/0 
requests. 


7 ee ae Halt I/O-request processing. (Quiesce 
I/0-request processing, if 0.) 


el eeeer Purge related requests only. (Valid only 
if a data-set purge is requested. ) 


O22 Reserved-—must be zero. 


ra eras Do not purge the TCB request-block chain 
of asynchronously scheduled processing. 


om Purge I/0 requests associated with a TCB. 


wl This is a 16-byte parameter list. 
Additional purge options are specified in 
bytes 12 to 15. CIf this bit is off, the 
list is 12 bytes long, and the purge 
routines do not put a return code in byte 
4 of this list or in register 15.) 


1,2,3 The address of a DEB if you're purging I/0 requests to 
a single data set. The address of the first DEB ina 
chain of DEBs if you're purging I/0 requests to more 
than one data set. (The next-to-the-last word of each 
DEB must point to the next DEB in the chain; the 
second word of the last DEB must contain zeros.) 


G A byte of zeros. (CIf bit 7 of byte 0 is on, the purge 
routines will put a code in this byte: X'7F' if the 
purge operation is successful; X'G0' if it is not 
successful. If bit 7 of byte 0 is off, then X'7F* 
appears in this byte.) 


5,6,7 The address of the TCB associated with the I/0 
requests you want purged (but only if you turned on 
bit 6 of byte 0). May be zeros if the TCB is the one 
you're running under. 


8 Driver 10. (Default value of X'00' implies that EXCP 
is the owner.) | 
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9,10,11 





12 


13 
14,15 





The address of a word in your storage or the address 
of the DEBUSPRG field (which is X'l1l‘! bytes more than 
the DEB address in this parameter list). At whichever 
address you specify, the purge routines store a 
pointer to the purged I/0 restore list, PIRL. In the 
PIRL is a pointer to the first IOB in the chain of 
IOBs. The location of the pointer and format of the 
chain are shown in Figure 28 on page 133. 


al ete This field is relevant for quiesce options 
only. 


A byte in which you can specify additional purge 
options. These are the bit settings and their 
meanings: 


Note: The following applies only if bit 7 of byte 0 
is set to one. 


Dux, atekcs Purge I/0 requests associated with an 
oe space. CYou must be in supervisor 
state. ) 


ARE lig en g.ck Check the validity of all the DEBs 
associated with the purge operation if 
this is a data-set purge. Validate this 
parameter list, whatever the type of purge 
operation, by ensuring that there are no 
inconsistencies in the selection of purge 
options. CIf you are in problem state, 
these actions are taken regardless of the 
bit setting.) 


i ae Ensure that I/0 requests will be 
reprocessed Crestored) under their 
original TCB. (If zero, and this byte is 
meaningful (Cbit 7 of byte 0 is on), the 
I/0 requests will be reprocessed under the 
TCB of the program making the restore 
request. ) 


= Must be zero. 
A byte of zeros. 
The 2-byte ID of the address space associated with the 


I/0 requests you want purged. COnly meaningful if bit 
2 of byte 12 is on.) 


Control is returned to your program at the instruction following 
the PURGE macro instruction. 
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Return Codes from PURGE Macro 


MODIFYING THE IOB 


If the purge operation was successful, register 15 will contain “os 
zeros. Otherwise, register 15 will contain one of the following ig y 
return codes: XN 


Code Meaning 


04€X'046") Your request to purge I/0 requests associated with a 
given TCB was not honored because that TCB did not point 
to the job step TCB, as it must when the requestor is in 
problem state. 


oS 
~~ 
e™™ 


M'08') Eqther you requested an adaress-sSpace purge operation, 
but were not in supervisor state, or you requested a 
data-~set purge operation, but supplied no data~area address 


in bytes l, 2, and 3 of the purge parameter list. 


200X'14') Another purge request has preempted your request. You 
may want to reissue your purge request ina time-controlled 
loop. 


Note: Register 15 will contain zeros, regardless of the outcome 
of the purge operation, if you set bit 7 in byte 0 of the 
parameter list to zero. 


CHAIN 


Note that, although it is not a recommended procedure, if you 

want to change the order in which purged I/0 requests are ee 
restored or prevent a purged request from being restored, you — 
may change the sequence of IOBs in the IOB chain or remove an ae. 
IOB from the chain. The address of the IOB chain can be _ 

obtained from the PIRL (see Figure 28). (The address of the 

PIRL is at the location pointed to by bytes 9 through 11 of the 

purge parameter list.) 
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( : PIRL 










PIRRSTR 20€X*14") 


Pointer to the first IOB. If ls, 
no I/0 request was quiesced. 













>IOBC1) Cwhere 1 is first IOB in chain) 





IOBRESTR 25(€19) 


Pointer to the next IOB in the 
chain. 


wenden Cwhere nis last IOB in chain) 


IOBRESTR 25(€19) 


Contains binary ls. 


(C Figure 28. The PIRL and IOB Chain 





RESTORE~~REPROCESS I70 REQUESTS 
The RESTORE macro is coded as follows: 


restore address——RX-type address, (2-12) or (1) 
address you specified at byte 9 of the purge parameter 


list. 


PERFORMING TRACK CALCULATIONS 


The TRKCALC macro performs track capacity calculations. The 
standard, list, execute, and DSECT forms of the macro are 
described. Examples of the TRKCALC macro follow the macro 
descriptions. Using TRKCALC, you may do the following: 


® Perform track capacity calculations 


e Determine the number of records of a given size that can be 
written ona full track or on the remainder of a track 


e Perform track balance calculations as follows: 
> Determine whether a given record size can be written in 


the space remaining on the track and return the new 
track balance. 
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~ Determine the maximum size record that can be written on 
the track if the given record does not fit 


= Determine the track balance if the last physical record 
is removed from the track. 


TRKCALC™—"STANDARD FORM 


The format of the TRKCALC macro is: 


TRKCALC FUNC TN={TRKBAL | TRKCAP} 
{»DEVTAB=addr |,UCB=addr |,» TYPE=addr} 
[, BALANCE=addr 1 
[»REMOVE={YES|NO} 1] 


[> eon e conten: 

{> RKDD=addr | »R=addr,K=addr,» DD=addr} 
[ »REGSAVE={LYES]NO}] 

[»MF=T] 





FUNCTN={TRKBAL | TRKCAP} 
specifies the function to be performed. 


Note: You must specify one of the three keywords, DEVTAB, 
UCB, or TYPE, to provide the macro a source for 
information. 

TRKBAL 


if REMOVE=NO is specified, TRKBAL calculates whether 
an additional record fits on the track and what the 
new track balance would be if the record were added. 
If REMOVE=YES is specified, TRKBAL calculates what the 
track balance would be if a record were removed from 
the track. The record to be added or removed from the 
track is defined by the RKDD parameter, or by the R, 
K, and DD parameters. 


If R=1 Cor the R value in the RKDD parameter is 1) and 
REMOVE=NO is specified, record 1 is added to an empty 
track; if R=1 and REMOVE=YES is specified, record 1 is 
deleted from the track, leaving an empty track. 


If R41, the specified record is added to or removed 
from the track. The input track balance may be 
supplied through the BALANCE parameter; if it is not 
supplied, it is assumed that the track contains 
equal-sized records as specified in the RKDD parameter 
Cor in the R, K, and DD parameters). 


When REMOVE=NO is specified, one of the following 
occurs: 


e If the racord fits on the track, register 0 
contains the new track balance. 


e If the record does not fit on the track and 
MAXSIZE=NO is specified, a “record does not fit" 
return code 1S given in register 15. 


e If the record does not fit and MAXSIZE=YES is 
specified, one of the following happens: 


- The data length of the largest record that 
fits in the remaining space is returned in 
register 0. 


~ A code is returned that indicates no record 
fits in the remaining space. 


When REMOVE=YES is specified, one of the following 
occurs: 
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e If R=1, register 0 contains the track capacity. 


e If R#¥l1, registers 0 contains the input track 
balance Csupplied through the BALANCE parameter) 
incremented by the track balance used by the input 
record. If the input balance is not supplied, 
register 0 contains the track capacity left after 
R-1l records are written on the track. 


TRKCAP 
calculates, and returns in register 0, the number of 
fixed-length records that may be written on a whole 
track CR=1) or ona partially filled track (CR#¥1). The 
records are defined by the K and DD values of the RKDD 
parameter, or by the K and DD parameters. 


One of the following occurs: 


e If R=l1, the BALANCE parameter is ignored and the 
calculation is made on an empty track 


® If R#l and the BALANCE parameter is omitted, the 
calculation is made for a track that already 
contains R-l records of the length defined by the 
K and DD values. 


e If R#l1l and the BALANCE parameter is supplied, the 
calculation is made for a track whose remaining 
track balance is the value of the BALANCE 
parameter. 


DEVTAB=addr-——RX-type address, (2-12), (0), (€19) 
addr specifies a word that contains the address of the 
Device Characteristics Table Entry (DCTE). If you specify 
a register, it contains the address of the DCTE, not the 
address of a word containing the address of the DCTE. The 
address of the DCTE can be found in the DCBDVTBA field of 
an opened DCB. 


UCB=addr—RxX-type address, (2-12), (0), €149) 
addr specifies the address of -a word that contains the 
address of the UCB. If you specify a register, it contains 
the address of the UCB, not the address of a word 
containing the address of the UCB. You must ensure that 
the UCB address is valid by verifying that byte 3 CUCBt2) 
in the UCB contains X'FF*. 


TYPE“-addr—RxX-type address, (2-12), €0), €19) 
you may specify the address of the UCB device type 
CUCBTBYTS4), or you may specify the l-byte UCB device type 
in the low-order byte of a register. 


BALANCE=addr——RX-type address, (2-12), €0), (149) 
you may specify either the address of a halfword containing 
the current track balance, or you may specify the balance 
in the low-order two bytes of a register. The value 
supplied may be the value returned when you last issued 
TRKCALC. If R=l1, the balance is reset to track capacity by 
TRKCALC, and your supplied value is ignored. This is an 
input value and is not modified by the TRKCALC macro. The 
resulting track balance is returned in register 0 and in 
the TRKCALC parameter list field STARBAL. 


REMOVE={YES | NO} 
indicates if a record is to be deleted from the track. 


YES 
specifies that the record identified by the record 
number (specified in the R keyword) is being deleted 
from the track. The track balance is incremented 
instead of decremented. 


Note: YES is valid only on a FUNCTN=TRKBAL call. 
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NO 7 
specifies that a record is not to be deleted from the 
track. NO is the default. 


MAXSIZE={YES | NO} 


YES 
If the specified record does not fit, the largest 
length of a record with the specified key length that 
fits is returned Cregister 0)... 
Note: YES is valid only on a FUNCTN=TRKBAL call. 

NO 


Maximum size is not returned. NO is the default. 


RKDD=addr-——RX-type address, (2-12), €0), (19) 
addr specifies a word containing a record number (1 byte), 
keylength (1 byte), and data length (2 bytes) Cbytes 0, l, 
and 2 and 3, respectively) or a register containing the 
record number, key length, and data length. R, K, and DD 
may be specified by this Keyword, or you may use the 
following three Keywords instead. 


R=addr—RX-type address, (2-12), €0), €14), or n 
you may specify either the address of the record number, or 
you may specify the record number using the low-order byte 
of a register or immediate data (n). Specify a decimal 
digit for n (immediate data). 


K=addr-——RX-type address, (2-12), €0), (149), orion 
you may specify either the address of a field containing 
the hexadecimal value of the record's key length, or you 
may specify the record's key length using the low-order 
byte of a register or immediate data (n). Specify a 
decimal digit for n Cimmediate data). 


DD=addr—RX-type address, (2-12), (0), (19), orn.” \ 
you may specify either the address of a field containing 
the hexadecimal value of the record's data length, or you 
may specify the record's data length using the low-order 
two bytes of a register or immediate data (n). Specify a 
decimal digit for n Cimmediate data). 


REGSAVE={YES | NO} 


YES 

| specifies registers 1 through 14 are saved and 
restored in the caller-provided save area Cpointed to 
by register 13) across the TRKCALC call. Otherwise, 
registers 1, 9, 10, 11, and 14% are modified. 
ot pa 0 and 15 are always modified by a TRKCALC 
call. 

NO 
specifies registers are not saved across a TRKCALC 
call. NO is the default. 

MF=I 


specifies storage definition for the TRKCALC parameter list 

and parameter list initialization, using the given 

pet ate nage then calling the TRKCALC function. MF=I is the 
efault. 
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TRKCALC~~EXECUTE FORM 


A remote parameter list is referred to and can be modified by 
the execute form of the TRKCALC macro. The TRKCALC routine is 
called. The description of the standard form of the macro 
provides the explanation of the function of each operand. 


[symbol] ] TRKCALC {FUNCTN={ TRKBAL | TRKCAP} ] 
[{,DEVTAB=fLaddr [x} | 
»UCB={addr [*} 1, TYPE=fLaddr1*}}1 
[,BALANCE=faddr [*}1 
[,REMOVE={YES|NQ}] 


[ »>MAXSIZE={YES | NO}] 

tf, RKDD=addr | » R=addr» K=addr» DD=addr}] 
[ , REGSAVE={YES NO} ] 

»MF=(CE,addr ) 





FUNCTN={TRKBAL | TRKCAP} 
1s coded as shown in the standard form. If this Keyword is 
omitted, any specification of REMOVE, MAXSIZE, LAST; and 
the RX form of BALANCE is ignored. In addition, DEVTAB is 
assumed if UCB is coded and a failure occurs, or if TYPE is 
specified. When you use FUNCTN, one of the Keywords 
CDEVTAB, UCB, or TYPE) must be spect tied to provide an 
information source. 


DEVTAB=addr |[*®—RX-type address, (2-12), (0), (€14) 
1s coded as shown in the standard form except for the X 
subparameter. Specify an * when you have inserted the 
address of the device characteristics table entry (DCTE) in 
the parameter list 


UCB=addr |*—RX- type address, (2-12), (0), (14) 
is coded as shown in the standard form except for the * 
subparameter. Specify an * when you have inserted the 
address of the UCB in the parameter list. 


TYPE=addr|[¥——-RX-type address, (2-12), (0), (14) 
is coded as shown in the standard form except for the xX 
subparameter. Specify an * when you have inserted the 
address of the UCB type CUCBTYP) in the parameter list. 


BALANCE=addr|*%—-RX-type address, (2-12), €0), €14) 
1s coded as shown in the standard form except for the xX 
subparameter. Specify an * when you have inserted the 
balance in the parameter list. 


REMOVE={YES | NO} 
is coded as shown in the standard form. 


MAXSIZE={YES [NQ} 
1s coded as shown in the standard form. 


RKDD=addr—RX-type address, (2-12), (0), (€14) 
1s coded as shown in the standard form. 


R=addr-——RX-type address, (2-12), (€0), (1494) orn 
1s coded as shown in the standard form. 


K=addr——RX-type address, (2-12), (0), (14), orn 
1s coded as shown in the standard form. 


DD=addr—RX-type address, (2-12), (0), €194), orn 
1s coded as shown in the standard form. 


REGSAVE={ YES | NO} 
is coded as shown in the standard form. 


MF=(E,addr) 
This operand specifies that the execute cen of the TRKCALC 
macro instruction and an existing data management parameter 
list are used. 
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E 
Coded as shown. 


addr—RX-type address, (0), €1), €2-12), or (149) 
specifies an in-storage address of the parameter list. 


The list form of the TRKCALC macro constructs an empty, in-line 
parameter list. By coding only MF=L, you construct a parameter 
list, and the actual values can be supplied by the execute form 
eee ecaae macro. Any parameters other than MF=L are 
ignored. 


TRKCALC | MF=L 


TRKCALC~“DSECT ONLY 


This call gives a symbolic expansion of the parameter list for 
the TRKCALC macro. No DSECT statement is generated. If a name 
is specified on the macro call, it applies, after any necessary 
boundary alignment, to the beginning of the list. The 
macro-~generated symbols all begin with "STAR". 


INPUT REGISTER USAGE FOR ALL FORMS OF 'MF' 


OUTPUT FROM TRKCALC 


Registers 0, 2 through 12») and 14 are available to provide input 
for keywords. 


Register 1 is used only to provide the address of the parameter 
list for an MF=E ca 


Register 13 may be used as input for keywords, if REGSAVE=YES is 
not specified. 


Register 15 is used as a work register to build the TRKCALC 
parameter list for the MF=E call; it is not available as an 
input register. : 


FUNCTN=TRKBAL 


The record fits on the track. Register 0 and STARBAL 
contain the new track balance. 


Record does not fit on the track. If MAXSIZE=YES is 
specified, a partial record does not fit either. 
Register 0 and STARBAL are set to zero. 


Record does not fit on the track. MAXSIZE=YES is 
specified, anda partial record does fit. Register 0 
and STARBAL are set to the maximum number of data 
bytes that fit on the remainder of the track with the 
specified keylength. 


Note: The keylength is excluded from the count of 
maximum data bytes. 
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STARBAL 
This is the track balance field of the TRKCALC 
eS parameter list. This field is first set to the track 

( | capacity if R=l, or to the supplied BALANCE value if 
R¥#1, or to the calculated balance if R#¥l and BALANCE 
are omitted. STARBAL is updated to the new track 
balance if the record fits; otherwise, STARBAL is left 
with the input track balance value. 


FUNCTN=TRKCAP 


Register 0 contains the number of records that fit on 
the track if R = 1, or the number of records that fit 
on the remainder of the track if R #1. 


No records of the length specified fit on a full track 
= = 1) or a partial track (R #1). Register 0 is set 
o zero. 


STARBAL 
This is the track balance field of the TRKCALC 
parameter list. This field is first set to the track 
capacity if R=l, or to the supplied BALANCE value if 
R41, or to the calculated balance if R#l and BALANCE 
are omitted. 


RETURN CODES FROM TRKCALC 


The TRKCALC macro passes a return code in register 15. The 
return codes and their meanings are as follows: 


Contents Meaning 


aa OOCX'00') Indicates that register 0 contains the new track 
ar: balance 


04(€X'04') Indicates that the record did not fit Cregister 0 = 0) 
08CX'08') Indicates that the record did not fit Cregister 0 
contains the maximum data length that does fit) 
TRKCALC MACRO EXAMPLES 
In this example, TRKCALC is coded to determine how many records 
| of a given size with l10-byte keys fit on a 3380 track. After 


issuing the macro, the number of records is saved in NUMREC: 


| TRKCALC FUNCTN=TRKCAP, TYPE=UTYPE,R=1,K=10,DD=DL,MF=CE,(1)) 


ST 0, NUMREC SAVE NUMBER OF RECORDS 


DL DC -H¥ xxx! DATA LENGTH 
l UTYPE DC X*'OE! 
NUMREC DS F MAX # OF RECORDS 


| In this example, TRKCALC is) coded to determine whether another 
record can fit ona track of a 3380, given a track balance. 


| TRKCALC FUNCTN=TRKBAL, TYPE=UTYPE,R=REC,K=KL,DD=DD, BALANCE=BAL, 
MAXSIZE=YES,MF=CE, C1) ) 


| UTYPE DC X'OE! 





REC DC X*¥xx! 
KL DC X'*xx! 
DD DC H ®¥ xxx F 
BAL DC H® xxxx § 
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ALLOCATING A DASD DATA SET 


The REALLOC macro builds a parameter list and issues SVC 32 to 
allocate a new data set based on a partial DSCB that describes 
the attributes of that data set. You can use the OBTAIN macro 
to get the format-1l DSCB of another data set and use it as a 
model for the new data set's DSCB which REALLOC will construct 
and write in the VTOC. 


The maximum number of extents that may be allocated are 
determined by the type of data set requested as defined by the 
data set organization CDSIDSORG) bytes and the data set 
indicator (CDSIDSIND) byte in the partial DSCB. If the DSI1DSORG 
indicates a VSAM data set organization and DSIDSIND indicates 
the data set is cataloged in an integrated catalog facility 
CICF) catalog, the maximum number of extents is 123. Otherwise, 
the maximum number of extents is 16. 


Note: User label data sets, ISAM data sets, and absolute track 
allocated data sets are not supported by the REALLOC macro. If 
a VSAM data set or data space is requested, REALLOC does not 
interface with VSAM or intergrated catalog facility catalog 
management. 


The DSISCALO field of the partial format-1l DSCB has a high order 
flag byte that describes the type of request and a 3-byte field 
containing the secondary allocation quantity. The following 
describes the flag byte: 


Contents Meaning 


X*CO! Cylinder request 

X'C8? Cylinder with CONTIG request 

X'80' Track request 

X*88! Track with CONTIG request 

X*40! Average block length request 

X*Gl1! Average block length with ROUND request 

X*G48! Average block length with CONTIG request 

xX'*49! Average block length with CONTIG and ROUND request 


Any settings other than the above are ignored. 


The REALLOC macro may be coded in the execute, DSECT, and list 
forms, but not the standard form. The calling program may be in 
supervisor or problem program state, and may be running in any 
key. The calling program must be APF authorized. 


REALLOC~~EXECUTE FORM 
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The format of the REALLOC macro in execute form is: 


| Esymbol REALLOC MF=(E,addr) 
» DSSIZE=addr1 (reg) 
» PDSCB=addr 
» UCB=addr 






[»MINAU=addr | (reg) 
C,PDSDIR=addr | (req) 


MF=(E,addr ) 
specifies that the execute form of the macro and an 
existing REALLOC parameter list are used. 
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addr—RX-type address, (0-12) 
specifies an in-storage address of the REALLOC 
(C parameter list. 


E 
Code as shown. 


DSSIZE=addr | (req) 
specifies the size of the data set to be allocated in 
tracks. If a cylinder request (X'CO' in the flag byte of 
DSISCALO) or average block with round request (X'G41') is 
made, the number of tracks specified 1s rounded up to the 
next full cylinder, if necessary. 


You may not specify the DSSIZE in terms of average block 
Size, even though the original data set may have been 
allocated with the number of average blocks (€X'GO'). 


addr—RX-type address 
specifies an in-storage address of a full word 
containing the data set size. 


(reg) 
specifies a register containing the size of the data 
set. Valid registers are 0 and 2-12. 


PDSCB=addr—RX-type address, (0), (2-12) 
specifies the address of the partial DSCB. The partial 
DSCB is comprised of the first 98 bytes of a format-1 DSCB. 
The first 44 bytes contains the data set name to be 
allocated. The contents of the partial DSCB are used, 
unchanged, in constructing the format-l DSCB. Only the 
field DSINOEPV (number of extents on the volume) of the 
partial format-1l DSCB is modified by allocation to reflect 
the actual number of extents allocated. 


es UCB=addr——RX-type address, (0), (2-12) 

| specifies the address of the UCB of the volume where the 

7 data set is to be allocated. The volume must be mounted 
and you must ensure that it remains mounted. 


MINAU=addr | (req) 
specifies the size of the minimum allocation unit in 
tracks. All primary extents for this data set are in 
multiples of this minimum allocation unit. This value does 
not apply to subsequent extensions of the data set. If the 
partial DSCB indicates the data set is to be allocated in 
cylinders (X'‘CO! or average block with round request 
CX'41'), this parameter is ignored. 


addr—RX-type address 
specifies an in-storage address of a full word 
containing the minimum allocation unit. 


(reg) 
specifies a register containing the minimum allocation 
unit. Valid registers are 0 and 2-12. 


PDSDIR=addr | (req) 
specifies the number of 256 byte directory blocks for a 
partitioned data set (PDS). This is a required keyword if 
the DSIDSORG indicates a partitioned data set. Otherwise, 
it 1s ignored. 


addr-—-RX-type address : 
specifies an in-storage address of a full word | 
containing the number of 256 byte PDS directory 


blocks. 
(req) 
PT specifies a register containing the number of 256 byte 
-, PDS directory blocks. Valid registers are 0 and 2-12. 
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REALLOC““DSECT ONLY 
The DSECT form of REALLOC is specified as follows: 


An example of the DSECT form expansion is: 


REALPL REALLOC MF=D 








REALPL DSECT DSECT FOR PARAMETER LIST 
RALPLID DS CL¢ EBCDIC "REAL FOR REALLOC 
RALNGTH DS AL2 LENGTH OF PARAMETER LIST 
RAERRCDE DS H ERROR CODE RETURNED FROM 
- X ALLOCATE (SVC 32) 
i RALRSVD DS F RESERVED 
RALDSSZ DS DATA SET SIZE 


F 
| RALMAU DS F MINIMUM ALLOCATION UNIT 
| RALPDSCB DS A PARTIAL DSCB POINTER 
RALUCB DS A : UCB POINTER 
RALDQTY DS F PDS DIRECTORY QUANTITY 
RALEND EQU ¥ END OF PARAMETER LIST 
RALENGTH EQU RALEND~REALPL LENGTH OF PARAMETER LIST 


REALLOC~“LIST FORM 


The list form of the REALLOC macro is specified as follows: 


[symbol] | REALLOC | MF=L 


»DSSIZE=addr | (reg) 
» PDSCB=addr 


» UCB=addr 
[ »MINAU=addr | (req) 
[»>PDSDIR=addr | (req) aa 





Refer to the execute form for an explanation of the parameters. 
An example of the list form expansion is: 


REALPL REALLOC MF=L 
CNOP 


0, 

REALPL EQU ¥ 

DC CL4"REAL’ EBCDIC *REAL* FOR REALLOC 

DC AL2C32) LENGTH OF PARAMETER LIST 

DC H*Q' ERROR CODE RETURNED FROM 
¥ ALLOCATE (SVC 32) 

DC =6F FOF RESERVED 

DC F'Q' DATA SET SIZE 

DC F‘Ot MINIMUM ALLOCATION UNIT 

DC ACO) PARTIAL DSCB POINTER 

DC AC0) UCB POINTER 

DC Fo PDS DIRECTORY QUANTITY 
RALOLE EQU % END OF PARAMETER LIST 


RETURN CODES FROM REALLOC 


Control returns to the instruction following the SVC 32 
generated by the REALLOC macro. If the data set was successfully 

allocated, register 15 contains zeros. Otherwise, register 15 
contains one of the following return codes: 





2 This is a cumulative list of DADSM allocation return codes. 
Some of these codes may not apply to the REALLOC macro. 
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Code 





Meaning 


004(X'04') Data set name of request already exists on this 
volume. Initial allocation not possible under 
the name given. 

008CX'08") No room available in the VTOC or VTOC index. 

O12CX'0C*) One of the following errors was encountered: 

e Permanent I/0 error 
° Error returned by CVAF 

O20CX"'14") Requested quantity not available. 

O28CX"1C*) ISAM DSORG is not supported. 

048CX'30") Register 0 contains a reason code indicating one 
of the following errors: 

e Reason Code 1 - Invalid REALLOC parmlist ID. 
e Reason Code 2 - Invalid REALLOC parmlist 
length. 

0520€X"'34") Invalid partial DSCB pointer. 

056C€X'38!") Not enough space on volume for directory. 

0720X"48") DOS VTOC cannot be converted to an OS VTOC. 

116C€X'74") User labels not supportea. 

120CX*78') DSSIZE=0 and MINAU is greater than 0. 

124CX"7C*) DSSIZE is not a multiple of MINAU. 

128CX*80") Directory space requested is larger than primary 
space. 

148 CX'94") Overlapping extents in the VTOC. 

L520X"98") Sl ae DOS split cylinder extents in the 

156CX'9C') DADSM allocation terminated due to possible VTOC 
errors. . 

L64CX"AG") Allocation terminated due to DOS stacked pack 
format. 

168CX*A8*) RACF DEFINE failed, data set already defined. 

172CX*AC*) User not authorized to RACF define data set. 

176CX"BO') Installation exit rejected this request with a 
return code of 8 

180CX'B4") Installation exit rejected this request with a 


fit. Lp 


return code of 4 


i-we Arr JDOYOL EM 


The MSGDISP macro displays a message on the IBM 3480. With 


MSGDISP, you can specify the message to be displayed and how to 
display it (for example, steady or flashing). The six main 
parameters of the macro and their functions are: 

MOUNT Displays an "M" in position 1 of the display area 
during a mount request until a volume is loaded and 
made ready The "M" is followed by the volume serial 
number and label type. 
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VERIFY Shows that a volume has been accepted by displaying 
its serial number and label type in positions 2 
through 8. | 





RDY Displays text in positions 2 through 7 while a data 
~" get 1S open. 


DEMOUNT | Displays a volume disposition indicator in position l 
until a volume is demounted. | 


RESET Clears the display area. 


GEN Provides the full range of display options, including 
the option to alternate two messages. 


All except the RDY parameter require that you be in supervisor 
; state, have a storage protect key of 0 through 7, or be 
authorized by the authorized program facility. 


The MSGDISP macro generates a parameter list as input to an SVC 
routine. 


MSGDISP may be coded in the standard, execute, and list forms. 
The formats for specifying MSGDISP with the six main parameters, 


and the return codes generated by MSGDISP, are given in the 
sections that follow. 


| MSGDISP—"DISPLAYING A MOUNT MESSAGE 
The format for specifying MSGDISP with the MOUNT parameter is: 


m4 
Ay 
Mt 
Ka 
Ne 
? i 


y TEST={NOTYES? J 
;WAIT={NOIYES} J 





MOUNT 
displays an "M" in position 1 of the display area during a 
mount request. The "M™" is followed by a volume serial 
number and label type. The display flashes on and off 
until a volume is loaded and ready. If the device is ready 
at the time a mount request is issued, the "M™ is not 
displayed. 


UCB=(req)—(2-12) 
Bpec.ce a register containing the UCB address for the 
evice. 


LABEL={£°ATI'N'I'S'I'X' laddr} 
displays the label type of the mounted volume in position 
8. If you specify an unknown label type other than a 
blank, a "?" is displayed. 


TAT 
specifies ISO/ANSI/FIPS CAL) or ISO/ANSI/FIPS with 
user labels (CAUL). Specify in apostrophes. 

™N? 
specifies no labels (NL), LTM CDOS), or bypass label 
processing (BLP). Specify in apostrophes. 

‘Ss! | 


specifies IBM Standard (SL) or IBM Standard with user 
labels (SUL). Specify in apostrophes. 





144 MVS/XA System-Data Administration 














BO neta it aor eee nh ace areata a a a Bet aN ee ei At 





"yx? 
specifies nonstandard labels (NSL). Specify in 
apostrophes. | 


addr—RX-type address, A-type address, or (2-12) 
specifies an in-storage address of an area containing 
an "A™, "N*, mst, or "X"* Csee the following 
explanations of these characters). For MF=L, you may 
only specify an A-type address. 


MF={L| CE,addr)} 
specifies either the execute or the list form of MSGDISP. 
If you do not specify this parameter, the standard form of 
the macro is used. 


L 





specifies the list form of MSGDISP. This generates a 
parameter list that can be used as input to the 
execute form. The execute form can modify the 
parameter list. 


(E,addr ) 
specifies that the execute form of the macro and an 
existing parameter list are used. 


addr—RX-type address, (1), or (€2-12) 
ee ee an in-storage address of the parameter 
ist. 


SER={ 'volser’ |addr} 
specifies the serial number of the volume to be mounted. 
The serial number is displayed in positions 2 through 7. 
If you do not specify SER, the system supplies the volume 
serial number. If the serial number is not available, a 
scratch volume is used, unless the volume use attribute 
indicates a default of "PRIVAT". 


( | 'volser' | 


specifies the volume serial number as a literal. 
Specify in apostrophes. 


addr-—RX-type address, A-type address, or (€2-12) 
specifies an in-storage address of the volume serial 
Speake i For MF=L, you may only specify an A-type 
address. 


TEST={NOI|YES} 
specifies whether to test the UCB to determine if the 
device is capable of displaying messages. 


NO 
specifies that the SVC routine will test the UCB. 


YES 
specifies testing the UCB before the SVC call. 


Note: TEST=YES requires you to include the UCB 
mapping macro CIEFUCBOB) in the source code. 


WAIT={NO| YES} 
specifies when control is returned to you. 


NO 
specifies that control is to be returned before I/0 is 
complete. I/0 return codes are not returned, and I/0 
errors are recorded in the same manner as any 
permanent error by the error recovery procedure. 

YES 


specifies that control is to be returned after I/0 is 
complete. 
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| MSGDISP—"DISPLAYING A VERIFY MESSAGE : 
The format for specifying MSGDISP with the VERIFY parameter is: 


VERIFY 
,UCB=(req) 
» LABEL={'A' PN US) UX" laddrd 


»MF= {L | (E,addrj}I 
»SER={'volser' laddr}] 
» TEST={NO| YES} 1 
»WAIT={NO 1 YES} ] 





VERIFY 
displays the serial number and label type of a volume that 
has been accepted in positions 2 through 8. Position 1 
remains blank. The display lasts until the next display 
request 1s executed. 


UCB=(req)—(2-12) 
Gece ee a register containing the UCB address for the 
evice. 


LABEL={'A'I'N'|'S"|"X! laddr} 
specifies label type of the mounted volume in position 8 of 
the display. If an unknown label type other than a blank 
is specified, a "7?" is displayed. 


TA? 
specifies ISO/ANSI/FIPS CAL) or ISO/ANSI/FIPS with 
user (AUL) labels. Specify in apostrophes. 

nk 
specifies no labels (NL), LTM CDOS), or bypass label 
processing (BLP). Specify in apostrophes. 

‘Ss! 
specifies IBM Standard (SL) or IBM Standard with user 
(SUL) labels. Specify in apostrophes. 

ty! . 


specifies nonstandard (NSL) labels. Specify in 
apostrophes. 


addr—RX-type address, A-type address, or (2-12) 
specifies an in-storage address of an area containing 
an "A™, "N®, 8S", or "X™ Csee explanations below for 
these characters): For MF=L, you may only specify an 
A-type address. : 


MF={LI(E,addr )} 
specifies either the execute or list form of MSGDISP. If 
you do not specify this parameter, the standard form of the 
macro is used. 


L 
specifies the list form of MSGDISP. This generates a 
parameter list that can be used as input to the 
execute form. The execute form can modify the 
parameter list. | 


(CE,addr) 
specifies that the execute ror of the macro and an 
existing parameter list is to be used. 


addr—RX- type address, (1), or (2-12) 
geecweres an in-storage address of the parameter 
is 


SER={ 'volser' laddr} 
specifies the serial number of the volume that has been 
verified. The serial number displays in positions 2 
through 7. If you do not specify SER, the system supplies 
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the volume serial number. If the serial number is not 
available, a scratch volume is used, unless the volume use 
( | attribute indicates a default of "PRIVAT". 


"volser' 
specifies the volume serial number as a literal. 
Specify in apostrophes. 


addr~——RX-type address, A-type address, or (2-12) 
specifies an in-storage address of the volume serial 
A Welab i For MF=L, you may only specify an A-type 
address. 


TEST={NO| YES} 
specifies whether to test the UCB to determine if the 
device is capable of displaying messages. 


NO 
specifies that the SVC routine will test the UCB. 


YES 
specifies testing the UCB before the SVC call. 


Note: TEST=YES requires you to include the UCB 
mapping macro CIEFUCBOB) in the source code. 


WAIT={NO| YES} 


specifies when control is to be returned to you. 


NO . 

specifies that control is to be returned before I/0 is 
complete. I/0 return codes are not returned, and I/0 
errors are recorded in the same manner as any 
permanent error by the error recovery procedure. 

P YES 

a specifies that control is to be returned after I/0 is 

| ; complete. 


| MSGDISP“—"DISPLAYING A READY MESSAGE 
The format for specifying MSGDISP with the RDY parameter is: 


RDY 
» DCB=addr 


i; MF= {L/(E,addr)}i 
r; TXT={€ 'msgtxt" laddr}1 





RDY | 
displays the text supplied in the TXT parameter in 
positions 2 through 7 while the data set is open. The 
display is steady (not flashing) and is enclosed in 
parentheses. The display is also written to the tape pool 
console Crouting code 3, descriptor code 7). 


DCB=addr 
specifies the address of a DCB opened to a data set on the 
mounted volume. If multiple devices are allocated, the 
message display is directed to the one containing the 
volume currently in use. 


Note: If multiple devices or multiple volumes are 
allocated, you may update a message display after an 
end-of-volume condition by using the EOV exit specified in 
a DCB exit list. In the case of a concatenated data set 
with unlike characteristics, the DCB OPEN exit may be used 
to update the display. 


addr-—RX- ype address, Ae type stideece: or (2-12) 
specifies an in-storage address of the opened DCB. 
For MF=L, you may only specify an A-type address. 
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MF={L] (E,addr)} 


specifies either the execute or 


this parameter is not specified, 


macro is used. 


L 
specifies the list form of 
parameter list that can be 
execute form. The execute 
parameter list. 


E,addr) 
specifies that the execute 
existing parameter list is 





list form of MSGDISP. If 
the standard form of the 


MSGDISP. This generates a 
used as input to the 
form can modify the 


form of the macro and an 
to be used. 








addr—RX-type address, (1), or (2-12) 
| 3 he aie an in-storage address of the parameter 
ist 


TXT={£ "msgtxt" laddr} 
specifies up to six characters to display in positions 2 
through 7 of the display. If you do not specify TXT, 
blanks are displayed. 


specifies the text as a literal. 
apostrophes. 


addr-—RX-type address, A-type address, or (2-12) 
specifies an in-storage address of an area containing 
the text to be displayed. For MF=L, you may only 
specify an A-type address. 


Specify in 


| MSGDISP—DISPLAYING A DEMOUNT MESSAGE 
The format for specifying MSGDISP with the DEMOUNT parameter is: = 


7 


MSGDISP DEMOUNT 
» UCB= 


[,DISP={ 


D'|'K'| 
MF= ELI Ce paddr) 
MLABEL= TI'N 


"laddr}] 


'R 

[> 7] 
[> i ae a X' laddr}] 
1 MSERSE "vo i oee to-mount' laddr}] 
[»SER={'volser' laddr}] 
[,>TEST={NO[YES} 1 

[ »WAIT={NO| YES} 1 





DEMOUNT 
Displays a volume disposition indicator in position 1 until 
the volume is demounted. Optionally, you may display the 
serial number of the volume to be demounted at the same 
time. The display flashes on and off. If a volume is not 
mounted on the device when the display request is executed, 
blanks are displayed. 


The demount message may be displayed alternately (flashing) 
with a mount message for the next volume by specifying the 
MSER parameter. 


UCB=(req)——( 2-12) 
pina ae a register containing the UCB address for the 
evice. 


DISP={'D' | 'K'|'R® laddr} 
specifies the character to display in position l, 
representing the volume disposition. 


‘p' 


Demount a public volume. Specify in apostrophes. 
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Note: "D" also displays when you specify an invalid 
character or when the volume use attribute is unknown 
{as in an automatic volume recognition CAVR) error 
when reading a label). 


tk? 
Keep a private volume and return it to the library. 
Specify in apostrophes. 


'R? 
Retain a private volume near the device for further 
use. Specify in apostrophes. 


addr—RX-type address, A-type address, or (2-12) 
specifies an in-storage address of an area containing 
a "p™, "K"™, or "R"™. For MF=L, you may only specify an 
A-type address. 


-MF={L|CE,addr J} 


specifies either the execute or list form of MSGDISP. If 
you do not specify this parameter, the standard form of the 
macro is used. 


L 
specifies the list form of MSGDISP. This generates a 
parameter list that can be used as input to the 
execute form. The execute form can modify the 
parameter list. | 


(E,addr } 
specifies that the execute form of the macro and an 
existing parameter list is to be used. 


addr-—RX-type address, (1), or €2-12) 
oo an in-storage address of the parameter 
ist. 


MLABEL={'A'I'N'I'S'|'X" laddr} 


displays the label type of the volume to be loaded and made 
ready following a demount, in position 8. If you specify 
an unknown label type other than a blank, a "7?" is | 
displayed. You may only specify this parameter if you also 
specify the MSER parameter. 


"A' 
specifies ISO/ANSI/FIPS CAL) or ISO/ANSI/FIPS with 
user (CAUL) labels. Specify in apostrophes. 

"NE 
specifies no labels (NL), LTM CDOS), or bypass label 
processing (BLP). Specify in apostrophes. 

'S* 
specifies IBM Standard CSL) or IBM Standard with user 
CSUL) labels. Specify in apostrophes. 

"yx! 


specifies nonstandard (NSL) labels. Specify in 
apostrophes. 


addr-——RX-type address, A-type address, or (€2-12) 
specifies an in-storage address of an area containing 
an "A™, #=N", #S", or "X" Csee the following 
explanations of these characters). For MF=L, you may 
only specify an A-type address. 


MSER={volser-to-mount'" laddr} 


displays the mount message for the next volume alternately 
(flashing) with the demount message. The display continues 
until you demount the current volume. At that time, the 
mount message will display (flashing) until you load the 
volume and make the device ready. If no volume is mounted 
at the time the demount and mount messages are executed, 
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only the mount message will display (flashing) until the 
volume is loaded and ready. 


~“~to~- 
specifies the volume serial number, as a literal, of 
the volume to be mounted. Specify in apostrophes. 


addr—RX-type address, A-type address, or (2-12) 
specifies an in-storage address of the volume serial 
number of the volume to be mounted. For MF=L, you may 
only specify an A-type address. 


SER={volser'" Jaddr} 
specifies the serial number of the volume to be demounted. 
The serial number is displayed in positions 2 through 7. 
If you do not specify SER, the system supplies the volume 
serial number. If the serial number is not available, a 
scratch volume is used, unless the volume use attribute 
indicates a default of "PRIVAT". 


specifies the volume serial number as a literal. 
Specify in apostrophes. 


addr—RX-type address, A-type address, or (2-12) 
specifies an in-storage address of the volume serial 
number. This parameter is not valid for the MF=L 
form. For MF=L, you may only specify an A-type 
address. 


TEST={NOI YES} 
specifies whether to test the UCB to determine if the 
device is capable of displaying messages. 





specifies that the SVC routine will test the UCB. 


= 
eee 


YES 
specifies testing the UCB before the SVC call. sa 


Note: TEST=YES requires you to include the UCB 
mapping macro CIEFUCBOB) in the source code. 


WAIT={NO] YES} 
specifies when control is to be returned to you. 


NO 
specifies that control is to be returned before I/0 is 
complete. I/0 return codes are not returned, and I/0 
errors are recorded in the same manner as any 
permanent error by the error recovery procedure. 

YES 


specifies that control is to be returned after I/0 is 
complete. 
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| MSGDISP“"RESETTING THE MESSAGE DISPLAY 
( The format for specifying MSGDISP with the RESET parameter is: 


RESET 
» {UCB=(reg) | ,UCBL=addr} 


[> MF={L](E,addr)}] 
[» TEST={NO| YES} ] 
[,WAIT={NO| YES} ] 





RESET 
clears all existing data on the display. If you specify 
WAIT=NO and the last service requested was a demount, the 
display is not cleared. 


After being cleared, the display will show the device's 
j status message (for example, a message indicating 
that the device is ready). 


UCB=(Creq)—(2-12) 
ieee a register containing the UCB address for the 
evice. 


UCBL=addr-—RX-type address, A-type address, (0), or (2-12) 
specifies the address of the list containing a maximum of 
64 words. Each word in the list contains the address of a 
UCB representing a device whose display is to be reset. 
The end of the list is indicated by a 'l' in the high-order 
bit of the last address in the list. If an error is 
encountered while processing the list, register 1 points to 
the associated UCB when you regain control. 


You cannot specify UCBL with TEST=YES and WAIT=NO. 


ie MF={L]| (CE,addr J} 
~ specifies either the execute or the list form of MSGDISP. 
. If you do not specify this parameter, the standard form of 
the macro 1s used. 


L 
specifies the list form of MSGDISP. This generates a 
parameter list that can be used as input to the 
execute form. The execute form can modify the 
parameter list. 


(E,addr) 
specifies that the execute form of the macro and an 
existing parameter list is to be used. 


addr—-RX-type address, (1), or (2-12) 
specifies the address of the parameter list. 


TEST={NO| YES} 
specifies whether to test the UCB to determine if the 
device 1s capable of displaying messages. 


specifies that the SVC routine will test the UCB. 


YES 
specifies testing the UCB before the SVC call. You 
cannot specify TEST=YES if you also specify the UCBL 
parameter. 


Note: TEST=YES requires you to include the UCB 
mapping macro CIEFUCBOB) in the source code. 


WAIT={NO| YES} 
specifies when control is to be returned to you. 
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NO | 
specifies that control is to be returned before I/0 is — 
complete. I/O return codes are not returned, and I/0 
errors are recorded in the same manner as any 
permanent error by the error recovery procedure. 





You cannot specify WAIT=NO if you also specify the 
UCBL parameter. 


specifies that control is to be returned after I/O is 
complete. | : 
Note: Demount messages can be reset only if WAIT=YES 
is specified. 

| MSGDISP-"PROVIDING THE FULL RANGE OF DISPLAY OPTIONS 


The format for specifying MSGDISP with the GEN parameter is: 


freq) 
[»FLASH={STEADY | STEADY21BLINK|IBLINK2| ALT} 1 
»MF={LICE,addr)}] 
» TEST={NOI YES} 1 


»TXT2=C 'altmsgtxt' laddr}] 
» VOL={STATIC | REMOVE | INSERT | SWAP} ] 


[ 
[ 
Pr TXTSt msatxt ' laddrs 
[ 
C,WAIT={NO|YES}] 





GEN 
specifies the full range of display options. 
UCB=(req)—(2-12) a 
peea oor a register containing the UCB address for the ‘a 
evice. 


FLASH={STEADY | STEADY2/| BLINKIBLINK2] ALT} 
specifies message display mode. 


Note: If you specify VOL=SWAP, messages will always be 
displayed as if you had specified FLASH=ALT. 


STEADY | 
specifies that the primary message (TXT) is to be 
displayed without flashing. 


STEADY2 
specifies that the alternate message (TXT2) is to be 
displayed without flashing. 


specifies that the primary message (TXT) flashes on 
and off at a rate of approximately two seconds on and 
one~half second off. 


BLINK2 
specifies that the alternate message (TXT2) flashes on 
and off at a rate of approximately two seconds on and 
one-half second off. 


ALT 
specifies that the primary and alternate messages (TXT 
and TXT2) flash on and off alternately at a rate of 
approximately two seconds on and one-half second off. 


MF={L|CE,addr)} 
specifies either the execute or the list form of MSGDISP. 
If you do not specify this parameter, the standard form of 
the macro is used. 
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specifies the list form of MSGDISP. This generates a 
parameter list that can be used as input to the 
execute form. The execute form can modify the 
parameter list. 


(E,addr ) 
specifies that the execute form of the macro and an 
existing parameter list is to be used. 


addr 
specifies an in-storage address of the parameter 
list. Specify either an RX-type address or a 
register in the range of 2 through l2. 


TEST={NO {YES} 
specifies whether to test the UCB to determine if the 
device is capable of displaying messages. 


specifies that the SVC routine will test the UCB. 


YES 
specifies testing the UCB before the SVC call. 


Note: TEST=YES requires you to include the UCB 
mapping macro CIEFUCBOB) in the source code. 


TXT=£ 'msatxt" laddr} 
specifies 8 characters to be shown in positions 1 through 8 
of the display. If you do not specify TXT, blanks are 
displayed. 3 


specifies the 8 characters as literals. Specify in 
apostrophes. 


addr-——-RX-type address, A-type address, or (2-12) 
specifies an in-~storage address of an area containing 
the 8 characters. For MF=L, you may only specify an 
A-type address. 


TXT2=f 'altmsagtxt" laddr} 
specifies 8 alternate characters to display in positions l 
through 8 of the display. If you do not specify TXT2, 
blanks are displayed. 


specifies the 8 characters as literals. Specify in 
apostrophes. 


addr—RxX-type address, A-type address, or (2-12) 
specifies an in-~storage address of an area containing 
the 8 characters. For MF=L, you may only specify an 
A-type address. 


VOL={STATIC | REMOVE | INSERT | SWAP} 
specifies message display mode, based on volume status. 


STATIC 
specifies that messages will display without regard to 
volume status until the next message request is 
executed, or until the next command initiates volume 
movement. 


REMOVE 
specifies that messages will display until the current 
volume is demounted. This parameter is ignored if a 
volume is not mounted when the request is executed. 


INSERT 
specifies that messages will display until a volume is 
present, the tape threaded, and the active/inactive 
switch is in the active position. This parameter is 
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SWAP 


WAIT={NO1| YES} 





ignored if a volume is loaded and ready when the 
request is executed. 


specifies that messages will always display as if 
FLASH=ALT were specified. 
displays alternately (flashing) until the current 
volume has been demounted. 
display (flashing) until a new volume is loaded and 
ready. If no volume is mounted when this parameter is 

specified, only TXT2 data will display (flashing) , 
until a new volume is loaded and ready. 


Then only TXT2 will 


specifies when control is to be returned to you. 


NO 


RETURN CODES FROM MSGDISP 


complete. 


specifies that control is to be returned before I/0 is 
I70 return codes are not returned, and I/0 
errors are recorded in the same manner as any 
permanent error by the error recovery procedure. 


specifies that control is to be returned after I/0 is 
complete. 


When the system returns control to the problem program, the 
low-order byte of register 15 contains a return code. The 
low-order byte of register 0 may contain a reason code as 


follows: 


Return 
Code (15) 


00¢X'00") 
04(0X'04") 
O8CX'08'*) 


O8CX'08') 


12€X'0C") 


Reason 
Code (0) 


01CX"01") 
02(X"02') 
03(X"03") 
04(X'04") 
05(X"05") 
06(X"06") 
11(X"0B") 
12¢X"0C") 
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Meaning 


Successful completion. 


Device does not support MSGDISP. 


Unauthorized request (failed TESTAUTH 
for proper authority level) or invalid 
ot parameters Cincluding DCB or 


Invalid parameter. 


Invalid DCB or DEBCHK error. 


Environmental error. 


Authorization violation. 


Invalid UCB. 


Invalid request. 


Unsuccessful ESTAE macro call. 


Unsuccessful GETMAIN request. 


I/O error CI/0O Supervisor posted the 
request for an error). 


Note: 


An I/0 error occurs for load 


display if the drive display has a 
hardware failure. 





The data from TXT and TXTZ2 | 

















If you get return code X*'04' or X'0C* on a RESET UCBL operation, 
register 1 points to the UCB associated with the error when you 
regain control. 
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This chapter describes how to maintain the system image library 
CSYS1.IMAGELIB) UCS and FCB images for the IBM 1403, 3203, and 
3211 Printers. It also describes how to maintain FCB images for 
the IBM 42465 Printer, the UCS image table in SYS1.IMAGELIB for 
the 3262 Model 5, 4245, and 4248 Printers, and how to retrieve 
an FCB image from SYS1.IMAGELIB for modification. 


The IEBIMAGE utility program is used to create and maintain 
control modules for the IBM 3800 Printing Subsystem: character 
arrangement table modules, graphic character modification 
modules, copy modification modules, library character set 
modules, and FCB modules. 


IEBIMAGE can also be used to create and maintain FCB modules for 
the 4248 Printer. FCB modules created for the 4248 can also be 
used with the 3262 Model 5 Printer; however, the 3262 Model 5 
does not support variable printer speeds or the horizontal copy 
feature of the 4248. For more information about IEBIMAGE, see 
Utilities. 


To use the information presented in this chapter, you should be 
familiar with the subjects of the following publications: 


e ata Rambaie thst tone Macks PastruetionRagepenca describes 
the SETPRT macro that can specify the UCS and/or FCB images 
to be used. 


8 JCL describes the UCB and FCB parameters of the DD statement 
that are processed at OPEN time. 


® 8 Cont Uni j j contains 
information on creating a user-designed chain/train for the 
1403 Printer. 


e 1 DY ; 0: P ] = ACR HTSLe —i8 Ves 1p 10NF =aeke Jpe = e i 
contains caeonmation on creating a user-designed train Fon 
the 3203 Printer. 


® B f., i Ln = 6 i q =) ziicif jU@CaADLe =eaa = Ldge -Eaie 
381] Printer Control Unit Component Description and 
Gperator's Guide contains information on creating a 


user-designed train for the 3211 Printer. 





@ ogrammi ] = 3 “If stnitia 
or Network Job Entry Facility for JES2 EOntaIne Peterence 
information for JES2. 

e JES3 Initialization and Tuning contains reference 


information for JES3. 


e The IBM 3262 Model 5, 4245 and 4248 Praianters have UCS images 
supplied in SYS1.IMAGELIB. The IBM-supplied image tables 
are shown in Figure 29 on page 159 and Figure 32 on 
page 163. For a list of all UCS images available, see: 


oe IBM 3262 Printer Model 5 Product Description, containing 
information on band IDs for the 3262 Model 5 Printer. 





: ar M Lpti 
Operator's Guide, Sentaining SAtoemation on band IDs for 
the $295 Printer. 


—- JBM 4248 Printer Description, containing information on 
band IDs for the 4248 Printer. 


The SPZAP service aid can be used to display and modify an 
existing member of SYSI. caer Use of SPZAP on load modules 
1s described in vi 
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| UCS IMAGES IN SYS1. IMAGELIE 


coo. Most IBM standard character set images are included i 

( ! SYS1.IMAGELIB at system generation time, through the. DATAMGT 
macro and an IODEVICE macro for the specified printer. (For 
details on the DATAMGT and IODEVICE macros, see System 
Generation Reference.) The standard character set images for 

the 1403, 3203, and 3211 Printers are shown below. 


1403 or 3203 AN, HN, PCAN, PCHN, PN, QNC, QN, RN, SN, 
TN, XN, YN 


3211 All, Gli, Hill, Pll, T1ll 


For the 3262 Model 5, 4245, and 4248 Printers, no UCS images are 
supplied in SYS1.IMAGELIB. Instead, a new UCS image is loaded 
into the buffer when the machine is powered on or the operator 
mounts a new band. See “Adding a UCS Image Name/Alias to a UCS 
Image Table™ on page 162 for information on how to access UCS 
images that are not supplied in SYS1.IMAGELIB. 






The 3262 Model 5, 4245 and 4248 Printers also load a default FCB 
image when the machine is powered on. The default FCB for the 
4248 is the last FCB loaded into the buffer. For the 4245, the 
default FCB is an ll-inch form with 6 LPI and a Channel 1 on the 
first print line. For the 3262 Model 5, the default FCB is an 
ll-inch form with 6 LPI, a Channel 1! on the third print line, 
and a Channel 12 on line 64. 


The alias names are defined for most installation-standard print 

—_ chains/trains/bands installable on a given printer. Alias names 

- are included in SYS]1.IMAGELIB (Cin the UCS image table) at system 
a generation time, with the real name of each image. 


Some print chains/trains’bands, such as SN and Gll, do not have 
alias names because there is no equivalent chain/train/band on 
other printers. You can assign an alias for these 
chains/trains/bands with the ALIAS statement of the linkage 
editor. (For more information on the ALIAS statement, see 
Linkage Editor and Loader.) For the 3262 Model 5, 4245 or 4248 
Printer, you can also add an alias name by modifying an entry in 
the UCS image table. See “Adding a UCS Image Name/Alias to a 
UCS Image Table™ on page 162. 


If an alias name is supplied, it is used to schedule a printer 
for SYSOUT data sets. If no alias is supplied, an 
installation-defined SYSOUT class or a printer routing code 
(specified with the DEST parameter of JCL) should be used to 
assign the data set to the correct printer. 


ADDING A UCS IMAGE TO THE IMAGE LIBRARY 


Using the assembler and linkage editor, you may add a UCS image 
to those that reside in SYS1L.IMAGELIB. No executable code is 
generated; the assembler prepares DCs, and the linkage editor 
puts them into SYS]1.IMAGELIB. The new UCS image must be 
structured according to the following rules: 
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The member name must be 5 to 8 characters long; the first 4 
acne must be the appropriate UCS prefix, as shown 
elow. | 


UCS1 - 14603 Printer | 
UCS2 - 3211 Printer Cor 3211 compatible printer) 
UCS3 - 3203 Printer 


These first four characters must be followed by a character 
set code, one to four characters long. Any valid 
combination of letters and numbers under assembler language 
rules is acceptable. However, the single letters U or C 
must not be used, because they are symbols for special 
conditions recognized by the system. The assigned character 
set code must be specified on the DD statement or SETPRT 
macro to load the image into the UCS buffer. 


You can supply an alias name for a new image with the ALIAS 
statement of the linkage editor. (For more information on 
the ALIAS statement, see Li j 2 


The first byte of the character set image load module 
specifies whether the image is a default. (Default images 
may be used by the system for jobs that do not request a 
specific image.) Specify the following in the first byte: 


For JES2: 
X'80" indicates a default image. 
X'G4O" <andicates that the output is to be folded. 
X'CO0* <aindicates default image and folding. 


X'00" aundicates that the image is not to be used as a 
default. | 


For non-JES2: 
X'*80" aundicates a default image. 


X*00* indicates that the image is not to be used as a 
default. 


The second byte of the load module indicates the number of 
lines (n) to be printed for image verification. See 
"Verifying the UCS Image™ on page 162 for more information 
on image verification. 


Each byte of the next n bytes indicates the number of 
characters to be printed on each verification line. For the 
3211 Printer, the maximum number of characters printed per 
line is 48; the bytes of associative bits (see note 5) are 
not printed during verification. 


The UCS image itself must follow the previously described 
fields. The image must fill the number of bytes required by 
the printer; see the table below for image lengths. Note 
that, because of assembler language syntax, two apostrophes 
or two ampersands must be coded to represent a single 
apostrophe or a single ampersand, respectively, within a 
character set image. 
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1403 240 bytes 


3203 304 bytes €240 characters followed by 64 
bytes of associative bits) 

3211 512 bytes (432 characters followed by 15 
bytes of X'00", 64 bytes of associative 
bits, and one reserved byte of X‘'00') 







Associative bits must be coded to prevent data checks when 


adding a UCS image to SYSL.IMAGELIB. See the appropriate 
Aas manual for more information on coding associative 
its. © 


UCS CODING EXAMPLES 


e Figure 29 contains an example of adding a 1403 UCS image, 
YN, to SYS1.IMAGELIB or the image library. Notes follow 
Figure 31 on page l1é6l. 


e Figure 30 on page 160 shows the code used to adda 3203 UCS 


image, YN, to SYS].IMAGELIB or the image library. 


® Figure 31 on page 161 shows the code used to add a 3211 UCS 


image, All, to SYS1L.IMAGELIB or the image library. 


4/7 ADDYN ) JOB MSGLEVEL=1 
“/ STEP EXEC PROC=ASMFCL, PARM.ASM="NODECK,LOAD', 
// PARM.LKED="LIST,OL,REFR, RENT, XREF* 
//ASM.SYSIN DD ¥ 
UCS1YN CSECT 
DC X*80' CTHIS IS A DEFAULT IMAGE) 
DC AL1(6) CNUMBER OF LINES TO BE PRINTED) 
DC AL1C39) €39 CHARACTERS TO BE PRINTED ON LINE 1) 
DC AL1(042) €42 CHARACTERS TO BE PRINTED ON LINE 2) 
DC AL1(039) C39 CHARACTERS TO BE PRINTED ON LINE 3) 
DC AL1039) (39 CHARACTERS TO BE PRINTED ON LINE 4) 
DC AL1(42) (42 CHARACTERS TO BE PRINTED ON LINE 5) 
DC AL1(039) C39 CHARACTERS TO BE PRINTED ON LINE 6) 
¥ THE FOLLOWING SIX LINES REPRESENT THE TRAIN IMAGE 
DC C*1234567890STABCDEFGHI JKLMNOPQRSTUVWXYZX, .' 
DC C'1234567890STABCDEFGHI JKLMNOPQRSTUVNXYZX, .#-$! 
DC C*1234567890STABCDEFGHIJKLMNOPQRSTUVNXYZX, .' 
DC C*1234567890STABCDEFGHIJKLMNOPQRSTUVWXYZX, . 
DC C1123456789 0STABCDEFGHIJKLMNOPQRSTUVWXYZX, . #-$" 


DC C*1234567890STABCDEFGHI JKLMNOPQRSTUVWXYZX, . 
7% | 
//LKED.SYSLMOD DD DSNAME= SYS1.IMAGELIBCUCSIYN),DISP=OLD, 
// SPACE= COVERRIDE SECONDARY ALLOCATION) 
Figure 29. Sample Code to Add a 1403 UCS Image to SY51.IMAGELIB 
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//ADYN3203 JOB MSGLEVEL=1 





“/STEP EXEC PROC=ASMFCL,PARM.ASM="NODECK,LOAD', 
// PARM.LKED="LIST,OL,REFR, RENT, XREF* 
77KSM.SYSIN DD X 7 
UCS3YN CSECT : 
DC xX*80! CTHIS IS A DEFAULT IMAGE) 
DC AL1(6) CNUMBER OF LINES TO BE PRINTED) 
DC AL1(C39) (39 CHARACTERS TO BE PRINTED ON LINE 1) 
DC AL1C42) €42 CHARACTERS TO BE PRINTED ON LINE 2) 
DC AL1(393 (39 CHARACTERS TO BE PRINTED ON LINE 3) 
DC. AL1(€393 €39 CHARACTERS TO BE PRINTED ON LINE 4) 
DC AL1C42) €42 CHARACTERS TO BE PRINTED ON LINE 5) 
DC AL1(€39) €39 CHARACTERS TO BE PRINTED ON LINE 6) 
% THE FOLLOWING SIX LINES REPRESENT THE TRAIN IMAGE 
DCO C'1234567890STABCDEFGHI JKLMNOPQRSTUVWXYZX, .* 
DC C'1234567890STABCDEFGHI JKLMNOPQRSTUVWXYZ*, . #-$* 
DC C*1234567890STABCDEFGHI JKLMNOPQRSTUVWXY ZX, .' 
DC C'1234567890STABCDEFGHI JKLMNOPQRSTUVWXYZX, .' 
DC OC 123456789 0STABCDEFGHIJKLMNOPQRSTUVWXYZX, . #-$" 
DC C'1234567890STABCDEFGHI JKLMNOPQRSTUVWXYZX, 
% THE FOLLOWING FOUR DC INSTRUCTIONS DEFINE THE ASSOCIATIVE BITS, 
% UCSB BYTE POSITIONS 241-304 
DC X*C01010101010101010100040000000000010" 
DC X*'101010101010101000404000000040001010' 
DC X*101010101010004000000000101010101010' 
DC X*10101010004000000000' 
END 
7% 
//LKED.SYSLMOD DD DSNAME=SYS1.IMAGELIBCUCS3YN), DISP=OLD, 
/1/ SPACE= COVERRIDE SECONDARY ALLOCATION) 


Figure 30. Sample Code to Add a 3203 UCS Image to SYS]1.IMAGELIB 
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fc  S/ADDAILIL JOB MSGLEVEL=1 
( SSTEP EXEC PROC=ASMFCL,PARM.ASM="NODECK,LOAD', 
// PARM.LKED="LIST,OL,REFR, RENT, XREF* 
//ASM.SYSIN DD % , 
UCS2ZA11 CSECT 
DC X*80' CTHIS IS A DEFAULT IMAGE) 
DC AL1(09) CNUMBER OF LINES TO BE PRINTED) 
DC AL1(48) (48 CHARACTERS TO BE PRINTED ON LINE 1) 
DC AL1(48) C48 CHARACTERS TO BE PRINTED ON LINE 2) 
DC AL1C48) €48 CHARACTERS TO BE PRINTED ON LINE 3) 
DC AL1(48) C48 CHARACTERS TO BE PRINTED ON LINE 4) 
DC AL1(C48) C48 CHARACTERS TO BE PRINTED ON LINE 5) 
DC AL1(48) (48 CHARACTERS TO BE PRINTED ON LINE 6) 
DC AL1(048) C48 CHARACTERS TO BE PRINTED ON LINE 7) 
DC AL1(048) (48 CHARACTERS TO BE PRINTED ON LINE 8) 
DC AL1(48) (48 CHARACTERS TO BE PRINTED ON LINE 9) 
% THE FOLLOWING NINE LINES REPRESENT THE TRAIN IMAGE 


xX NOTE 2 AMPERSANDS MUST BE CODED TO GET 1 IN ASSEMBLER SYNTAX 
DC C'1<.+IHGFEDCBAX$—-RQPONMLKJ% , &&ZYXWVUTS/0#098765432' 
DC C'1l<.+IHGFEDCBAX$-RQPONMLKJ% , &&ZYXWVUTS/0#098765432' 
DC Ctl<.+IHGFEDCBAX$—-RQPONMLKJ%, &&ZYXWVUTS/0#098765432' 
DC C'1l<.+IHGFEDCBAX$-RQPONMLKJ%, &&ZYXWVUTS/0#098765432' 
DC C'i<.+IHGFEDCBAX$—-RQPONMLKJ% , &&ZYXWVUTS/9#098765432' 
DC C'1l<.+ITHGFEDCBAX$-RQPONMLKJ% , &&ZYXWVUTS/0#098765432' 
DC C'L<.+IHGFEDCBAX$-RQPONMLKJ%, &&ZYXWVUTS/0#098765432' 
DC C'l<.+IHGFEDCBAX$—-RQPONMLKJ%, &&ZYXWVUTS/0#098765432' 
DC C*1<.+THGFEDCBAX$-~RQPONMLKJ%, &&ZYXWVUTS/0#098765432' 


DC 15X*00° ~ CRESERVED FIELD, BYTES 433-447) 
% THE FOLLOWING FOUR DC INSTRUCTIONS DEFINE THE ASSOCIATIVE BITS, 
% UCSB BYTE POSITIONS 448-511 

DC X*€010101010101010101000490404240004010' 


DC X*101010101010101000404041000040401010' 


DC  X*101010101010006040000000101010101010" 
_ | DC  X*101010100046040444800' 
om DC = X00 CRESERVED FIELD, BYTE 512) 
END 
1% 
//LKED.SYSLMOD DD DSNAME=SYS1.IMAGELIBCUCS2A11),DISP=OLD, 
11 SPACE= COVERRIDE SECONDARY ALLOCATION) 


Figure 31. Sample Code to Add a 3211 UCS Image to SYS1.IMAGELIB 


Notes to Figure 29 on page 159, Figure 30 on page 160, and 
Figure 31: 


1. The RENT and REFR linkage editor attributes are used for 
performance considerations in a paging environment. They 
are required attributes. 


2. For the 3203 and 3211 Printers, the 64 bytes of associative 
bits must be coded to avoid data checks. To determine how 
to code these bits for a particular image, see 

j fe) e script] a 's Gui or IBM 

inte 216 Inte changeable ain Ca idge, and 38] 

n inti 





3. Executing the ASMFCL procedure does not actually generate 
executable code. The assembler/linkage editor is used to 
place the UCS image into SYS1L.IMAGELIB. 


G4. The SPACE parameter is overridden here because the ASMFCL 
cataloged procedure has secondary allocation specified. 
Elimination of the override causes the original secondary 
allocation amount to be used. 
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| Verifying the UCS Image 
For the 1403 Cwith the UCS feature), 3203, 3211, 3262, and 4245 
Printers, the UCS image can be displayed on the printer for. 
visual verification using either of the following parameters: 
e In JCL: UCS=(character set code, »VERIFY) 
e In the SETPRT macro: UCS=(character set code>,»,V) 


These parameters can also be used for the $248 Printer. 





Because the UCS image cannot be read directly from the 3262 
Model 5 and 4248, only the header information on the 
verification display will be printed out. The verification 
display header appears in the format shown below. 


UCS IMAGE VERIFICATION image id [,FOLD] [description] 





The 1l- to 4-character name of the UCS image. 


The descriptive information supplied for this UCS image in 
the UCS image table. 
The 4245 also, optionally, prints the image. 


For more aap pene ane he VERIFY ge eles, see JCL 


} 





— 


SYS1.IMAGELIB does not contain UCS images for the 3262 Model 5, 
4245, or 42468 Printers. Instead, the image for each band is 
stored in the printer, and automatically loaded into the UCS 
buffer when the machine 1s powered on or a new band is 
installed. Information about these images is recorded in the 
IBM-supplied UCS image table, which resides in SYS1.IMAGELIB. 


[ UCS Image Table Structure 


SYS1.IMAGELIB contains one UCS image table for each er of 
printer that supports image tables. The image table ee an 
entry for most installation-standard IBM-supplied bands. 

the 4245, the table is called UCS5. For the 4248 and the 3262 
Model 5, the table is called UCS6. A typical UCS image table 
entry is shown in Figure 32 on page 163. 
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Byte O 1 91011 12 16 17 


. Description data’ 
Length of description data! 


Lengths of verification lines? 
(VLENGTH); one byte per line 


Number of verification tines 
Reserved (set to zero) 
Description offset (set to zero if omitted) 


Verification offset (set to zero if omitted) 


Flag Byte: X‘00’= Non-default image 
X'40'= Fold image 
X’60’= Fold image/ Default 
X’80’= Default image 
UCS Image Name 
UCS Image Name or Alias (1-4 character 
name, left-justified and padded to a 
4-character length with blanks, if necessary) 


( Length of this entry 


Figure 32. UCS Image Table Entry Format 


Notes to Figure 32: 
1. This field is optional. 


2. This field is optional for the 4245 Printer. For the 4248, 
this field does not apply and is set to X‘'00". 


The contents of the UCS image table UCS5 CIGGUCS5 macro), for 
the 4245 Printer, are shown in Figure 33 


Taner [wat | ves | oofeate us Geeoo | 
raver [a [wo [0575205 an Senos 
[uo | $21 At imase 
uo | «eae ei imase 
[no | Nondofault UCS image 
[uo 940875205 HW imase 


Figure 33 (Part 1 of 2). UCS5 Image Table Contents 
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Name Default 


PL21 


ca 


PL21 
SN21 
SN21 
TN21 
TN21 | TN 

TN21 
TN21 
GN21 
GN21 
GN21 


RN21 ~RN21 

RN21 RN 1403/3203 RN image 
KA21 KA21 Nondefault UCS image 
KA21 4041 NO | 42468 4041 image 

KA22 KA22 Nondefault UCS image 
FC21 FC21 Nondefault UCS image 
FC21 4161 4248 4161 image 


Figure 33 (Part 2 of 2). UCS5 Image Table Contents 


3211 H11l image 





4248 4101 image 
Nondefault UCS image 


3211 Pll image 


4248 4121 image 


Nondefault UCS image 







1403/3203 PN image | 


4248 41Cl image 





Nondefault UCS image 
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The contents of the UCS image table UCS6 CIGGUCS6 macro), for 
the 4248 Printer, are shown in Figure 34. , 


Name Description 

40El Default UCS image 

40E1 | AN2l | NO — | 4245 AN21 image 

40—E1 | AN | NO —_—‘ |: 140373203 AN image 

40E1 No 3211 All image 

4101 | 4101 | NO | Nondefault UCS image 

4101 | HN21 | NO  — | 4245 HNZ1 image 
No 
| No 


4101 1403/3203 HN image 


6101 3211 H1l image 


4ic1_ | 41cl | No | Nondefault UCS image 
4ic1 | GN21 | No — | 4245 GNZ1 image 
4icl_| Gil | NO _—'| 3211 G11 image 

4121 | 4121 | No | Nondefault UCS image 
4121 | PLzl1 | NO | 4245 PL21 image 

4121 | No =| 140373203 PN image 
4121 | Pll | 3211 Pll image 

4181 Nondefault UCS image 
4181 42465 TN21 image 

4181 1403/3203 TN image 
4181 3211 Tll image 

4061 Nondefault UCS image 
4ocl_ | 40cl | Nondefault UCS image 
4201 | 4201 | No 


Figure 34. UCS6 Image Table Contents 


Nondefault UCS image 
4245 EC2i amage 
Nondefault UCS image 
4245 SN21l image 
Nondefault UCS image 
4245 KA21 image 


Note: The image tables for the 4245 and 4248 Printers include 
USA and Canada band IDs only. To support other national band 
IDs, you must modify the UCS image table. See "Adding/Modifying 
a UCS Image Table Entry™ on page 166. 


The 3262 Model 5 Printer uses the 4248 UCS image table, UCS6. 
However, no 3262 Model 5 band names or aliases are provided by 
IBM in UCS6. In order to use 3262 Model 5 UCS images, you must 
add the names and aliases to UCS6 yourself. "Adding/Modifying a 
UCS Image Table Entry™ on page 166 describes how to add entries 
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to the UCS image table. For a list of the bands available for 
the 3262 Model 5, see JBM 3262 Printer Mode] 5 Product 


| Adding/Modifying a UCS Image Table Entry 


If you plan to use a new UCS image name/alias with the 3262 
Model 5, 4245, or 4248 Printer, you must add an entry for that 
image name/alias to the appropriate UCS image table. Similarly, 
if you want to select a new default image or change the 
description on an old image, you must make the change in the 
image table. 


To build new UCS table entries, or to change the format of old 
entries, use the following procedure: 


1. Issue the IGGUCSIT macro, as described below, to build a new 
UCS image table entry. A new entry is built even if it is 
intended to replace an existing entry supplied by IBM. 
Because the new entry is found first, the previous entry is 
never found and thus is effectively replaced. 


2. Include the UCS image table, source using the IGGUCSS5 or 
IGGUCS6 macro, both of which are found in SYS1.MACLIB. 


3. Reassemble the image table module CUCS5 or UCS6). 
G. Link-edit the reassembled module into SYS]1.IMAGELIB. 
The IGGUCSIT macro instruction has the following format: 
IGGUCSIT MF={LIST|IDSECT} 
»NAME=image name 
[,ALIAS=im 


image aliasl 
DEFAULT={VES|NO}1 
DESCR=desce 


[> 

c, sscription] 

[, DEVICE= (4245 [4248}] 
{»VLENGTH=(nl>n2>. ° endl 





F={LIST | DSECT} 


specifies the form of the macro instruction. 


LIST 
produces a UCS image table entry based on the 
information supplied in other IGGUCSIT parameters. If 
LIST is selected or allowed to default, the NAME 
parameter must also be coded. 


DSECT | 

produces a DSECT for a single UCS image table entry, 
Similar to the sample entry shown in Figure 32 on 
page 163. If you code DSECT, all other parameters of 
IGGUCSIT are ignored. 


LIST is the default. 


NAME=image name 
specifies the 1 to 4 character UCS image name. 


ALIAS=image alias 
specifies a 1 to 4% character alias name for the UCS image. 
If ALIAS is not specified, the image name coded in the NAME 
parameter will be entered in the UCS image table. 


DEFAULT={YES |NQ} 
indicates whether the new UCS image is to be used as a 
default value. 


VES 
indicates that this UCS image is a default. Default 
images are used by the system for jobs that do not 
request a specific image. 
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NO 


indicates that this UCS image should not be used as a 
default. 


If the DEFAULT parameter is not specified, the new UCS 
image is not used as a default. 


DESCR= 
epaci fice descriptive information about the new UCS image. 
c can be up to 32 EBCDIC or hexadecimal 
characters long. You cannot use EBCDIC and hexadecimal 
characters in combination. 


Descriptive information is placed in the header line of the 
verification display, following the real UCS image name. 

If you omit the DESCR parameter, no description appears in 
the display. For more information on the verification 
display, see "Verifying the UCS Image™ on page 162. 


If VLENGTH is not specified for the 4245 Printer, the DESCR 
parameter 1S ignored. 


DEVICE=£4245 | 4248} 
specifies the type of device for which | an image table entry 
is to be created. 


If you specify MF=LIST on the first invocation of the 
IGGUCSIT macro, DEVICE defaults to 4245. The default for 
subsequent invocations is the printer type that you 
specified Cor the default) on the first invocation. Table 
pierre with different DEVICE specifications are not 
allowed. 


For the 3262 Model 5 Printer, DEVICE=4248 should be 
specified in order to create the appropriate form of the 
image table entry. 


VLENGTH=(nl»>n2». . n) 
specifies the Length(s) of each line in the UCS 
verification display. The length of each line must be 
paths separately, even if all lines are of the same 
ength. 


nl is the length of print line 1; n2Z is the length of print 
line 2; nis the length of the last print line. To display 
the complete image, the sum of the verification line 
lengths should equal 350. 


For details on the verification report, see "Verifying the 
UCS Image™ on page 162. 


The VLENGTH parameter is not valid for the 3262 Model 5 or 
4248 Printer. 


EXAMPLES OF ADDING TO THE UCS IMAGE TABLE 


| Example 1: Adding a New Band ID to the 4245 UCS Image Table (UCS5) 


In this example, the band name RPQ1 with description "RPQ BAND" 
1s added to UCS5. In the UCS verification display, 7 lines of 
50 characters each are printed. Macro IGGUCS5 causes the UCS 
image table source (Cas distributed by IBM) to be included in the 
table entry. 
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4/UCS5 JOB. 
// | EXEC ASMFCL, | 
Sf PARM.ASM="NODECK,LOAD', 
S/ PARM.LKED="OL,RENT,REUS' 
//SYSPRINT DD SYSOUT=A 
//ASM.SYSIN DD X 
TITLE "UPDATED UCS5 IMAGE TABLE’ 
UCS5 CSECT 
IGGUCSIT NAME=RPQ1, 
VLENGTH=(50,50,50,50,50,50,50), 
DESCR="*RPQ BAND! 
IGGUCS5 7 
END 
7X 


7/LKED. SYSLMOD DD DSN=SYS1.IMAGELIBCUCS5), DISP=OLD, 
// SPACE= COVERRIDE SECONDARY eee 


Notes to Example 1: 


1. The RENT and REUS linkage editor attributes are used for 
performance considerations in a paging environment. They 
are required attributes. 


2. Executing the ASMFCL procedure does not actually generate 
executable code. The assembler/linkage editor is used to 
place the UCS image table entry into SYS1.IMAGELIB. 


3. The SPACE parameter is overridden here because the ASMFCL 
cataloged procedure has secondary allocation specified. 
Elimination of the override causes the original secondary 
allocation amount to be used. 


Example 2: Adding a New Default Entry to the 4248 UCS Image Table (UCS6). 


In the following example, the band name GO0E1 with description 
"4Q0E1 DEFAULT BAND™ is added to UCS6 and defined as a default 
band. An alias name, HN21l, is also defined for band 40E1. 
Macro IGGUCS6 causes the UCS image table source Cas distributed 
by IBM) to be included in the table entry. 


7/UCS6 JOB... 
// EXEC ASMFCL, 
// PARM.ASM="*NODECK,LOAD', 
// PARM.LKED="OL,RENT,REUS' 
7/SYSPRINT DD SYSOUT=A 
“/7ASM.SYSIN DD X 
TITLE ‘UPDATED UCS6 IMAGE TABLE' 
UCS6 CSECT 
IGGUCSIT NAME=40E1, 
DEVICE=4248, 
ALIAS=HN21, 
DEFAULT=YES, 
DESCR="40E1 DEFAULT BAND* 
IGGUCS6 
END 


7% 
//\LKED.SYSLMOD DD DSN=SYS1.IMAGELIBCUCS6),DISP=OLD, 
// SPACE= COVERRIDE SECONDARY ALLOCATION) 


Note that this method creates a duplicate entry for 40El that 
becomes the first entry in the table. Because the table is 
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searched sequentially, the new entry is always found before the 
old entry, thus effectively replacing the old entry. 


Notes to Example 2: 


1. The RENT and REUS linkage editor attributes are used for 
performance considerations in a paging environment. They 
are required attributes. 


2. Executing the ASMFCL procedure does not generate executable 
code. The assembler/linkage editor places the UCS image 
table entry into SYSI]1.IMAGELIB. 


3. The SPACE parameter is overridden because the ASMFCL 
cataloged procedure has secondary allocation specified. 
Elimination of the override causes the original secondary 
allocation amount to be used. 





Two standard FCB images, STD] and STD2, are included in 
SYS1.IMAGELIB during system generation for the following 
printers: 


3203 
3211 
4245 
3262 Model 5 
4248 


The 42498 and 3262 Model 5 Printers also accept FCBs that can be 
used with the 3203, 3211, and 4265 Printers. (These are 
referred to as 3211 format FCBs.) 


STD1 sets line spacing at 6 lines per inch for an 8-172 inch 
form; STD2 is a default FCB image that sets line spacing at 6 
lines per inch for an ll-inch form. Channels for both images 
are evenly spaced, with Channel 1 on the fourth Line and Channel 
9 on the last line. See Figure 35 on page 170 and Figure 36 on 
page 170 for sample STDI1 and STD2 images. 


The 3262 Model 5, the 4245, or the 4248 Printer loads a default 
FCB image into the buffer when the machine is powered on. The 
3262 Model 5 default FCB image is an ll-inch form with 6 lines 
per inch, a Channel 1 on the third print line, and a Channel 12 
on line 64. The 4245 default FCB image is an ll-inch form with 
6 lines per inch and a Channel 1 on the first print line. The 
4248 default FCB image is the last FCB image loaded. 


You should use the IEBIMAGE utility to create and modify FCB 
modules for the 3800 Printing Subsystem. You should also use it 
to create and modify FCB images for the 3262 Model 5 or 4248 
Printer €4248 format FCBs). For information on IEBIMAGE and the 
format of the 4248 FCB image, see Utilities. 
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FCB2STD1 CSECT 
DC X*80' 


DC AL1(€48) 
DC X'000000' 


DC X'O1! 

DC X*000000' 
DC X*02' 

DC X'000000' 
DC X*03' 

DC X*'000000° 
DC X*04! 

DC X'000000' 
DC X'O5' 

DC X*000000' 
DC X'06'° 

DC X*000000' 
DC X*07' 

DC X*000000' 
DC X'08' 

DC X'000000' 
DC X*OA* 

DC X*000000' 
DC X"OB' 

DC X*000000' 
DC X'0C! 

DC X*000000' 
DC X'19!° 

END 








DEFAULT | 
FCB IMAGE LENGTH 


LINE 


LINE 
LINE 
LINE 
LINE 
LINE 
LINE 
LINE 


1, 2, 3 

CHANNEL 1 
» 6, 7 

8, CHANNEL 2 

10, Il 


4, 
5 


9, 
12, 


13, 14 


16, 
17, 


CHANNEL 
» 15 
CHANNEL 


46, 47 
CHANNEL 


Figure 35. Sample of the Standard FCB Image STDI 


FCB2STD2 CSECT 
DC 


DC X'O1' 

DC X*0000000000' 
DC ? ¥ 

DC X*0000000000* 
DC X03! 

DC X*0000000000' 
DC X'04! 

DC X*0000000000' 
DC X*05! 

DC X*0000000000' 
DC X*06'° 

DC X*0000000000' 
DC ’ | 

DC X*0000000000' 
DC X'038! | 
DC X*0000000000' 
DC X'OA' 

DC X*0000000000' 
DC t | 

DC X*0000000000' 
DC X'OC* 

DC X*00' 

be X*19! 

END 


DEFAULT 
FCB IMAGE LENGTH 


LINE 
LINE 
LINE 
LINE 
LINE 


LINE 16 


LINE 
LINE 
LINE 
LINE 
LINE 
LINE 
LINE 
LINE 


4 


10, 
ll, 
a 
17, 
22, 
23, 
28, 
29, 
34, 


1, 2, 3 
» CHANNEL 1 
5 6 


» 7, 


CHANNEL 
12, 13, 
CHANNEL 
18, 19, 





= 48 


nN DBD WwW BH WW 


10 
11 
12 
9-END OF FCB IMAGE 


= 66 


CHANNEL 4 


24, 25, 
CHANNEL 


62, 63 


CHANNEL 12 


CHANNEL 


Figure 36. Sample of the Standard FCB Image STD2 
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9-END OF FCB IMAGE 
































You may adda 3211 format FCB image to those that reside in 
SYS1.IMAGELIB, using the assembler and linkage editor. No 
executable code is generated; the assembler prepares DCs, and 
the linkage editor puts them into SYS1.IMAGELIB. The new FCB 
image must be structured according to the following rules: 





1. The member name may not exceed eight bytes. The first four 
characters of the name must be FCB2. The characters that 
follow identify the FCB image and are referred to as the 
"image identifier™ CID). Any combination of valid assembler 
language characters can be used, with the exception of a 
single "C™ or "U", because these are used by the system to 
recognize special conditions. The image identifier must be 
specified in the FCB keyword of a DD statement or in the 
SETPRT macro to load the image into the FCB buffer. 


2. The first byte of the FCB load module specifies whether the 
image 1s a default. (Default images may be used by the 
system for jobs that do not request a specific image.) 
Specify the following in the first byte: 





X'*80"* andicates a default image 
X'Q0" andicates a nondefault image 


3. The second byte of the load module indicates the number of 
bytes to be transferred to the control unit to load the FCB 
image. This count includes the byte, if used, for the print 
position indexing feature. 


G4. The third byte of the load module (the first byte of the FCB 
image) is either the print position indexing byte, or the 
lines-per-~inch byte. The print position indexing byte is 
optional and, when used, precedes the lines-per-inch byte. 

[ The 4245 and 4248 Printers accept and discard the index byte 
if it is present, because neither printer supports the 
indexing feature. A description of the print po ae 


ers indexing feature and = use will be found in 
| te ter able Jrai a and 38 
, mpc - | ipti nd 0 3 





The special index flag in the third byte contains X'80!' plus 
a binary index value, from 1 to 32 (the default is 1). This 
index value sets the left margin: 1 indicates flush-left; 
any other value indicates a line indented that many spaces. 


The form image begins with the lines-per-inch CLPI) byte. 
The LPI byte defines the number of lines per inch (6 or 8) 
and also represents the first line of the page. It may or 
may not also contain a channel identifier. 


Typically, the length of an FCB image is consistent with the 
length of the form it represents. For example, an 8-1/2 
inch form to be printed at 6 LPI has an FCB image that is 51 
bytes long (8-1/2 inches times 6 LPI). 


The LPI byte appears as follows: 
X'in't sets 8 LPI 
X'On" sets 6 LPI 


5. All remaining bytes Clines) must contain X'0n', except the 
last byte, which must be X'ln'. The letter n can be a 
hexadecimal value from 1 to C, representing a channel Cone 
to 12), or it can be 0, which means no channel is indicated. 


In Figure 37 on page 172, an FCB load module is assembled and 
added to SYS1.IMAGELIB. The image defines a print density of 8 
lines per inch on an ll-inch form, with a right shift of 15 line 
character positions (1-1/2 inches). 
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//ADDFCB 


//STEP 
17 


4/7 ASM.SYSIN 
FCB2ID1 CSECT 
XTHIS EXAMPLE IS FOR 





JOB MSGLEVEL=1 | 
EXEC PROC=ASMFCL,PARM.ASM="NODECK,LOAD', 


DD 


1% 
//LKED.SYSLMOD DD 
17 





PARM.LKED="LIST,OL,REFR, RENT, XREF* 
x 


A FORM LENGTH OF 11 INCHES WITH 8 LPI (88 LINES) 





X'80" THIS IS A DEFAULT IMAGE 

AL1(89) LENGTH OF FCB IMAGE AND INDEXING BYTE 
X'8F! OFFSET 15 CHARACTERS TO THE RIGHT 
X'10° 8 LINES PER INCH-NO CHANNEL FOR LINE 1 
XL4'0! G4 LINES NO CHANNEL 

X'ol! CHANNEL 1 IN LINE 6 

XL6"0* 6 LINES NO CHANNEL 

x02" CHANNEL 2 IN LINE 13 

XL6'0! 6 LINES NO CHANNEL 

X03" CHANNEL 3 IN LINE 20 

XL6'0' 6 LINES NO CHANNEL 

X"04' CHANNEL 4 IN LINE 27 

XL6"0! 6 LINES NO CHANNEL 

X'05! CHANNEL 5 IN LINE 34 

XL6"O! 6 LINES NO CHANNEL 

X*06! CHANNEL 6 IN LINE 41 

XL6'O! 6 LINES NO CHANNEL 

X07! CHANNEL 7 IN LINE 48 

XL6'O! 6 LINES NO CHANNEL 

X"08! CHANNEL 8 IN LINE 55 

XL6'0' 6 LINES NO CHANNEL 

xFog' CHANNEL 9 IN LINE 62 

XL6*O! 6 LINES NO CHANNEL 

X"OA' CHANNEL 10 IN LINE 69 

XL6'0! 6 LINES NO CHANNEL 

X*' OB? CHANNEL 11 IN LINE 76 

XL6"0! 6 LINES NO CHANNEL 

XFoc' CHANNEL 12 IN LINE 83 

XL4'O° G4 LINES NO CHANNEL _ 
X*10" POSITION 88 LAST LINE IN IMAGE . 


DSNAME=SYS1. IMAGELIBC(FCB21D1),DISP=OLD, 
SPACE= COVERRIDE SECONDARY ALLOCATION) 


Figure 37. Sample Code to Assemble and Add an FCB Load Module to SYS1.IMAGELIB 


Notes to Figure 37: 


1. 


The RENT and REFR linkage editor attributes are used for 
performance considerations in a paging environment. They 
are required attributes. 


Executing the ASMFCL procedure does not actually generate 
executable code. The assembler/linkage editor is used to 
place the FCB image into SYS1.IMAGELIB. 


The SPACE parameter is overridden here because the ASMFCL 
cataloged procedure has secondary allocation specified. 
Elimination of the override causes the original secondary 
allocation amount to be used. 
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RETRIEVING AN FCB IMAGE FROM SYS1. IMAGELIB 


If you want to modify an FCB image in virtual storage before 
loading it into a forms control buffer, you can use this 
sequence of macro instructions to read the FCB image into 
virtual storage. 


1. An IMGLIB macro instruction, along with the OPEN parameter 


2. A BLDL macro instruction to determine whether the FCB image 
you want is in the image library 


3. A LOAD macro instruction to load the image into virtual 
storage 


After the image has been read in, you should issue the IMGLIB 
macro instruction with the CLOSE parameter and the address of 
the DCB that was built by the first IMGLIB macro. A SETPRT 
macro instruction can be used to load the forms control buffer 
with the modified image. Printers other than the 3800 will 
require the use of an FCB entry in an exit list, as described in 


The format of the BLDL and SETPRT pal is given in Data 
3; the eccwat of the 
LOAD macro is given in V1SO Vi 
c j 


The format of the IMGLIB macro is shown below: 
IMGLIB| {OPEN|CLOSE,addr} 


OPEN 
specifies that a DCB is to be built for SYS1.IMAGELIB and 
that SYS1.IMAGELIB is to be opened. The address of the DCB 
1s returned in register 1. 


CLOSE 
specifies that SYS1.IMAGELIB is to be closed. 


specifies the RX-type address of the word that points to 
the DCB. If coded in the form Creg), the register in 
parentheses then contains the address of the DCB, not the 
address of the fullword. 


Return codes from the IMGLIB OPEN macro are shown below: 


OCX'O00') Operation successful. 


GOX'04') Either the volume containing 
SYS1.IMAGELIB is not mounted or a 
required catalog volume is not mounted. 


8CX'08") ae SYS1.IMAGELIB does not exist on 
he volume to which the catalog pounees 
hh SYS1.IMAGELIB is not cataloged. 


L2CX'0C*) An error occurred in reading the catalog 
or VTOC. | 


BLDL and LOAD are the only macros that may refer to the DCB 
built by the IMGLIB macro. 











Chapter 7. Maintaining SYS1.IMAGELIB 173 

















The system assigns an alias for each installation-standard print 
chain not actually defined on a given printer. This provides 
JES2 with flexibility in scheduling printers for SYSOUT data 
sets. For example, a request for the 14903 TN train would be 
assigned the Tll train if the data set were printed ona 32ll. 
The assigned alias names that follow the naming conventions 
currently used in SYS1.IMAGELIB are: 


Image Alias 


UCSI1AN UCSI1AI1] 
UCS1HN UCS1H11 
UCSIPN UCSIP11 
UCSITN UCS1T11 
UCS2A11 UCS2AN 
UCS2H11 UCS2HN 
UCS2P11 UCS2PN,UCS2RN,UCS2QN 
UCS2T11 UCS2TN 


The image and alias names are included in SYS]1.IMAGELIB at 
system generation. 


Some trains, such as SN and Gll, do not have aliases because 
neither has an equivalent train on the other printer. An 
installation can assign an alias, if it SO chooses. CFor 


details about the ALIAS statement, see 
Loader.) 


f an alias 1s supplied, JES2 will use it. If an —_ 
alias is not supplied, an installation-defined SYSOUT class ora | , 
printer routing code (specified via the DEST parameter) should i 
be used to assign the data set to the correct printer. Ifa 
SYSOUT class or a printer routing code is not used and if JES2 
is directed to print a data set ona printer for which the. 
proper image 1s not supplied, JES2 notifies the operator. The 
operator can then print the data set with a valid train or 
Aarne the data set to the proper printer via the 'SE! 
command. 


If an installation defines a new train, it can supply an alias 
name for that train, via the linkage editor ALIAS statement, 
when including the image in SYS1.IMAGELIB. 


THE 321] INDEXING FEATURE 


JES2 supports the 3211 Indexing Feature in two ways: 
l. Specification of the INDEX parameter on the /XOUTPUT card. 
2. The extended FCB image: 


JES2 supplies two special FCBs: FCB26 for 6 lines per inch 

and FCB28 for 8 lines per inch (specified as FCB=6 and 

FCB=8, respectively). These FCBs contain a channel 1 

indication in position 1, a special index flag in the third 

ocr and the number of lines per inch in the fourth byte of 
e image. 


The special index flag in the third byte of FCB26 and FCB28 
contains X'80*" plus a binary index value, in the range 1 to 
32 (default=1). The index value sets the left margin (1 
indicates flush-left position; other values cause 
indentation of the print line by N-1l positions). 
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IBM 3203 MODEL 5 PRINTER 


Chapter 8. 





If any other FCB images are to be used by JES2, they must | 
specify channel 1 in position 1; otherwise, JES2 incorrectly 
positions the forms in the printer. CSTD1 and STD2 do not 
specify channel 1 in position 1 and therefore must not be 
specified, unless altered, for JES2.) 


If the third byte of any other FCB image contains a data 
character (specifying the number of lines per inch) other 
than X'80', JES2 uses that specification and supplies an 
index value of l. 


The IBM 3203 Model 5 Printer is treated as a 3211 Printer by 
JES2, except that the 3203 Model 5 does not support the 3211 
indexing feature, and any indexing commands from JES2 are 
ignored by the 3203 Model 5. The 3203 Model 5 uses 3211 FCB 
images and its own unique UCS images. UCS images are listed in 


? r= 
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The load modules for CATALOG CSVC 26), SCRATCH CSVC 29), and 
RENAME CSVC 30) contain as their entry points the dummy modules 
IGGO026DU, IGGO29DU, and IGGO30DU, respectively. These dummy 
modules immediately pass control to the first processing module 
for their respective SVCs without performing any processing : 
themselves. The CATALOG dummy module IGGO26DU receives control 

, from SVC 26 and immediately passes control to module IGCO0002F. 
The SCRATCH dummy module IGGO29DU receives control from SVC 29 
and immediately passes control to module IGCO002I. The RENAME 
dummy module, IGGO30DU, receives control from SVC 30 and 
immediately passes control to IGC00030. 


The load module for SCRATCHCSVC29) also contains the dummy 
module IGGOZ29DM. The SCRATCH dummy module IGG029DM receives 
control from IGG0290D when an error return code of 4 or 8 is 
indicated, and immediately passes control to the location 
pointed to by register 14 


If you require special processing either before or after SVC 26, 
29, or 30, you replace the appropriate dummy module(€s) with your 
own module(s). Your replacement modules must follow all the 
characteristics and programming conventions for SVC routines. 
For information on characteristics of SVC routines, programming 
conventions for SVC routines, writing SVC routines, and 
sda ibaea SVC routines, see Supervisor Services and Macro 

. Your modules may replace IGGO26DU, IGGO29DU, 
TGGO29DM, and IGGO30DU in SYS1.AO0OSD0 prior to system generation, 
or you may replace the dummy modules in SYSI1.LPALIB after system 
generation. Information on how to replace the dummy modules 
with your modules can be obtained from the appropriate link-edit a, 
step of the STAGE I system generation output. You may also —_— 
obtain link~edit information from the STAGE I system generation ae, 
macro SGIECGDM in SYS1.AGENLIB. You may apply PTFs to CATALOG, 7 
SCRATCH, or RENAME with SMP without modifying your own versions 
of IGGO26DU, IGGOZ29DU, IGGO29DM, and IGGO30DU. 


The prolog of each of the dummy modules contains register 
conventions and other information about these modules. 





. 


wv 
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The BUFNO Keyword in the DCB macro and the BUFNO subparameter of 
the DCB keyword in the DD statement determine how many buffers 
are allocated when accessing a partitioned or sequential data 
set using QSAM. The NCP keyword in the DCB macro determines how 
many un-CHECKed READ or WRITE macro instructions are allowed 
when accessing a sequential or partitioned data set using BSAM; 
one buffer is used for each READ or WRITE macro instruction. 


The sequential access method can construct a channel program to 
transfer as many as 30 buffers or 240000 bytes of data, 
whichever is less. If BUFNO or NCP is less than 30, no more 
than that number of buffers can be transferred with a single 
channel program. 


BUFNO is defaulted in OPEN to five if it is not specified for a 
QSAM DCB; NCP is defaulted to one in OPEN if it is not 
specified. The QSAM access method manages buffers. The user 
program must manage buffers when it uses BSAM 


PERFORMANCE CONSIDERATIONS 


Buffer number and block size influence the rate at which data 
can be transferred and the operating system overhead per block. 
The use of more buffers reduces C(Cper block transferred) the EXCP 
and IOS overhead and the time waiting for the DASD device to 
seek to the requested cylinder and rotate to the requested 
record (device latency time). However, if more buffers are 
allocated than a program can effectively process, the virtual 

- pages containing those buffers will be paged out, effectively 

res adding to the system overhead for the job. A large number of 

| | buffers also cause a large amount of real storage to be 

allocated to the job while the data is being transferred. 


A job in a low-performance group may get swapped out more 
frequently than a higher priority job. The number of buffers 
allocated for the job contributes to the number of pages that 
have to be swapped out. 


Programs that access data sets with small block size (for 
example, 80) can easily make effective use of 30 buffers, which 
fit in, at most, two 4096-byte pages. The advantage of 30 
buffers over the default of five buffers is great: one channel 
program versus six channel programs to transfer 30 blocks. 


At the other end of the spectrum, usage of data sets with large 
blocking factors such as full-track blocking on 3350 or 
half-track blocking on 3380 can still be effective when only 
three or four buffers, rather than five or more, are specified. 
The slightly lower DASD performance and small increase in EXCP 
and I0S instruction costs should be more than offset by a 
reduction in paging or swapping in a constrained environment. 


It can be seen that proper selection of buffer number can have a 
positive effect on the elapsed time of a job and the system 
overhead associated with the job. The DCB OPEN installation 
exit can use installation criteria for a default buffer number 
for QSAM DCBs (for a description of the OPEN installation exit, 
see "DCB OPEN Installation Exit™ on page 100.) The NCP field of 
the DCB must be set by the program for BSAM DCBs. 
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CVAFDIR MACRO 
OVERVIEW OF THE CVAFDIR MACRO 
ful an indexed or nonindexed VTOC, the CVAFDIR macro may be used 
CO: 
e Read or write a DSCB by specifying the name of the data set 
it represents 
e Read or write a DSCB by specifying its address 
In addition, for an indexed VTOC, the macro may be used to: 
° Read or write VTOC index records 
e Read and retain in virtual storage the first high-level 
VIER, and VIERs used during an index search. 
® Read and retain in virtual storage the space map VIRs 
e Free VIRs retained in virtual storage 
SYNTAX 
a, 
[label] CVAFDIR ACCESS=READ|[WRITEIRLSE N J 


DSN=addrl 


[> 
[»BUFLIST=addrl 

[,VERIFY=YES|NO1] 

[,UCB=(Creg) | DEB=addr]1 

[> Deedee ett ein rc JNOKEEP | 
[ 

[ 

[ 

[> 


OKEEP,addr J] 
»MAPRCDSEVES | (VES, addr) INO! 


O,addr)] 
» LXRCDS= KEEP LCKEEP, addr} |NOKEEP| 
(NOKEEP,addr)] 
» BRANCH=YES?|NO| (VES, SUP) | (YES» PGM) 3 
MF=IILI(E,addr)] 





1The default is SUP if YES is coded. 


ACCESS: READ OR WRITE A DSCB OR VIR(S}, OR RELEASE BUFFER LISTS 


When ACCESS is READ or WRITE, a single DSCB is accessed for an 
indexed or nonindexed VTOC, or one or more VIRS are accessed for 
an indexed VTOC. 


ACCESS=READ 
Specifies that a single DSCB or one or more VIR(s) are to 
be read into a buffer whose address is ina buffer list. 


If the buffer list if for a DSCB, only one entry is used in 
the buffer list. The first entry with the skip bit set to 
zero and with a nonzero buffer address is used. 


All VIRCs) whose buffer list entry has the skip bit off 
will be read into a buffer. 


DSN and BUFLIST are required if ACCESS=READ for a DSCB 
buffer list. 
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ACCESS=WRITE 
Specifies that a single DSCB or one or more VIRs are to be 
written from buffer(€s) whose address is ina buffer list. 


WRITE is permitted with BRANCH=NO only if the caller is. 
authorized by APF. 


DSN and BUFLIST are required if ACCESS=WRITE for a DSCB 
buffer list. 


If any buffer list entry has its modified bit set, only 
those entries with the modified bit set will be written. If 
no modify bits are on, all VIRsS will be written. 


ACCESS=RLSE 
Applies only to VIR buffer lists. It requests the release 
of one or more buffers in the VIR buffer list chain 
identified in the BUFLIST keyword, and the release of each 
buffer list for which all buffers are released. 


DSN and BUFLIST are not required if ACCESS=RLSE. 


Only buffers in the buffer list with the skip bit set to 
zero and with a nonzero buffer address are released. The 
clad list is not released if any entry has the skip bit 
set to one. 


For an indexed VTOC, if ACCESS=RLSE is coded, buffer lists 
and buffers pointed to by the BUFLIST keyword will be 
released, along with buffer lists supplied in the CVAF 
parameter list CVMRCDS and CVIRCDS fields. If the CVMRCDS 
or the CVIRCDS buffers are supplied in the BUFLIST field, 
either directly or indirectly through chaining, the keyword 
MAPRCDS=YES, IXRCDS=KEEP, or MAPRCDS=C(NO,0), 
IXRCDS=CNOKEEP,0) must be coded to prevent CVAF from 
freeing the buffers more than once. If buffers are 
released, the CVAF parameter list field pointing to the 
buffer list will be updated. 


SPECIFY THE NAME OF THE DSCB 


DSN=addr 
DSN specifies the address of a 44-byte data set name of the 
DSCB to be accessed. 


DSN is required if ACCESS=READ or WRITE and the request is 
to read or write a DSCB. If a 140-byte DSCB is specified: 


e CVAF validity checks the storage location, but ignores 
the contents of the location. 


e You must specify an argument that points to an extent 
within the VTOC. 


SPECIFY ONE OR MORE BUFFER LISTS 


BUFLIST=addr 
The BUFLIST keyword contains the address of a buffer list 
used to read or write a DSCB or VIRs. 


VERIFY THAT A DSCB IS A FORMAT-0 DSCB 


CVAF will verify that the DSCB is a format-0 DSCB before 
writing the DSCB. The first four bytes of the key will be 
compared with binary zeros. If the key does not start with 
four bytes of zeros, the DSCB will not be written and an 
error code will be returned. 
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VERIFY=NO | 
CVAF will not test the key of the DSCB. 


Note: VERIFY applies only when writing a 140-byte DSCB. VERIFY 
is ignored when a VIR is written. , 


| UCB]DEB: SPECIFY THE VTOC TO BE ACCESSED 


UCB=(req) 
Supplies the address of the UCB for the unit whose VTOC is 
to be accessed. An unauthorized caller may not supply a _ 
UCB to CVAF. 


Note: ‘Code the address of the UCB parameter as register 
(2-12). Coding an RX-Type address here gives you 
unpredictable results. , 


DEB=addr 
Specifies the address of a DEB opened to the VTOC you want 
to access. CVAF does not allow output requests to the VTOC 
or VTOC index if you specify the DEB subparameter. If you 
are not authorized, you cannot perform any asynchronous 
activity (such as EXCP, CLOSE, EOV) against the data set 
represented by the DEB because CVAF removes the DEB from 
the DEB table for the duration of the CVAF call. If you 
are not authorized (neither APF authorized nor in a system 
key), you must specify a DEB address, not a UCB, to 
CVAFDIR. See "Identifying the Volume™ on page 26 for 
further details. 


If you supply a previously obtained CVAF I/0 area through the 
IOAREA keyword, you need not specify the UCB or DEB keyword. 

Otherwise you must specify either the UCB or DEB keyword. If 
you specify a UCB, the UCB address in the CVPL is overlaid by 


the UCB address in the I/0 area. | ~~ 
If you supply both the UCB and DEB addresses in the CVPL, CVAF Ne? 


uses the DEB address and overlays the UCB address in the CVPL 
with the UCB address in the DEB. 


IOAREA: KEEP OR FREE THE I/O WORK AREA 


ITOAREA=KEEP 
Specifies the CVAF I/0 area associated with the CVAF 
parameter list is to be kept upon completion of the CVAF 
request. JIOAREA=KEEP may be coded with BRANCH=NO only if 
the caller is authorized CAPF or system key). 


If IOAREA=KEEP is coded, the caller must issue CVAF with 
IOAREA=NOKEEP specified at some future time, whether or not 
any further VTOC access is required: for example, the 
recovery routine of the caller of CVAF. 


Coding IOAREA=KEEP allows subsequent CVAF requests to be 
more efficient, as certain initialization functions can be 
bypassed. Neither DEB nor UCB need be specified when a 
previously obtained CVAF I/0 area is supplied; neither can 
they be changed. 


When IOAREA=KEEP is first issued, CVAF returns the CVAF I/0 
area in the CVAF parameter list CCVIOAR). Subsequent calls 
of CVAF may use that same parameter list, and CVAF will 
obtain its I/0 area from the CVIOAR. 


When processing on the current volume is finished, release 
all areas that were kept. 


ITOAREA=(KEEP,> addr ) 
Provides the address of a previously obtained I/O area. If 
a different CVAF parameter list is used, the previously 
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obtained I/0 area may be passed to CVAF by coding its 
address as the second parameter of the IOAREA Keyword. 


Causes the work area to be freed upon completion of the 
CVAF request. 


IOAREA=(NOKEEP, addr ) 
Causes a previously obtained work area to be freed upon 
completion of the CVAF request. 





MAPRCDS: KEEP OR FREE MAPRCDS BUFFER LIST AND BUFFERS 


This keyword applies to an indexed VTOC only and specifies the 
disposition of the MAPRCDS buffer list and buffers. 


MAPRCDS=YES 
Specifies that the buffer list and buffers are to be 
retained at the end of processing. 


If no buffer list address is in the CVAF parameter list, 
CVAF will read the MAP VIRs into buffers it obtains. The 
buffer list that contains the address and RBAs of the VIRs 
can be accessed after processing from the CVAF parameter 
list field, CVMRCDS. The buffer list and VIR buffers are 
in your protect key: subpool 0 if you are not authorized; 
229 if you are. 


When processing on the current volume is finished, release 
all areas that were kept. 


MAPRCDS=(YES, addr) 
If YES is coded and the buffer list address (CCVMRCDS in 
CVAF parameter list) is supplied, VIRs are not read. 


_ The CVMRCDS buffer list used in CVAFDIR macro can be passed 
| to another CVAF macro call through the MAPRCDS keyword. 


If MAPRCDS=YES is coded for a nonindexed VTOC, the function 
is performed, but an error code will be returned. 


=NO | 
If MAPRCDS=NO is coded, all the buffers without the skip 
bit on in the buffer list whose address is in the CVMRCDS 
field of the CVPL will be freed. If all the buffers are 
freed, the buffer list will also be freed. 


MAPRCDS=(NO, addr ) : 
Causes buffer lists and buffers previously obtained by CVAF 
to be freed. 


You must free buffer lists and buffers obtained by CVAF. This 
can be done in one of three ways: 


e By coding MAPRCDS=NO on the CVAFDIR macro that obtained the 
buffers 


e By coding MAPRCDS=NO on a subsequent CVAF macro 


e By coding CVAFDIR ACCESS=RLSE and providing the address of 
the buffer list in the BUFLIST keyword 


Note: You must enqueue the VTOC and reserve the unit to 
maintain the integrity of MAP records read. 
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IXRCDS: RETAIN VIERS IN VIRTUAL STORAGE 
This keyword applies to indexed VTOCs only. 


IXRCDS=KEEP 
Specifies that VIERs read into storage are to be kept in 
virtual storage. The VIERs are retained even if processing 
cannot complete successfully. The CVAF parameter list in 
field CVIRCDS will have the address of a buffer list 
oo the VIR buffer addresses and RBAs of the VIERs 
read. | 





The index search function will dynamically update the 
buffer list and, when necessary, obtain additional buffer 
lists and chain them together. | 


If KEEP is specified and no buffer list is supplied to CVAF 
in the CVPL, CVAF will obtain a buffer list and buffers and 
read the first high-level VIER. The address of the buffer 
list is placed in the CVMICDS field of the CVPL. The first 
~ high-level VIER will be checked for the VXFHLV bit and to 
see whether the VXVISE bit is off. 


The buffer list and VIR buffers are in your protect key. 
The subpool is 0 if you are not authorized; it is subpool 
229 if you are. 


If IXRCDS=KEEP is coded for a nonindexed VTOC, a request to 
read or write a DSCB will be performed, but an error code 
will be returned. 


When processing on the current volume is finished, release | 
all areas that were Kept. 


IXRCDS=( KEEP, addr ) 
The index records buffer list address from one CVAF request 2 
is being passed to this CVAF parameter list by specifying ee 
its address as the second parameter in the IXRCDS keyword. oe 
=NOKE 


If NOKEEP is coded, the VIERs that are accessed (if any) 
are not retained. Furthermore, the buffer list supplied in 
the CVIRCDS field in the CVAF parameter list is released, 
as are all buffers found in the buffer list. If the skip 
bit is set in any entry in the buffer list, the buffer and 
buffer list will not be freed. 


IXRCDS=(NOKEEP, addr ) 
Specifies that previously accessed VIERs are not to be 
retained. 


You must free buffer lists and buffers obtained by CVAF. This 
can be done in one of three ways: 


e By coding IXRCDS=NOKEEP on the CVAFDIR macro that obtained 
the buffers 


e By coding IXRCDS=NOKEEP on a subsequent CVAF macro 


6 By coding CVAFDIR ACCESS=RLSE and providing the address of 
the buffer list in the BUFLIST keyword 


Note: You must enqueue the VTOC and reserve the unit to 
maintain the integrity of the VIERs read. 
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BRANCH: SPECIFY THE ENTRY TO THE MACRO 


BRANCH=( YES, SUP) : 
Requests that the branch entry to CVAFDIR be used. You 
must be in supervisor state. Protect Key checking is 
bypassed. 


An 18-word save area must be supplied if BRANCH=YES is 
coded. No lock may be held on entry to CVAF. SRB mode is 
not allowed. 


BRANCH=YES 
Equivalent to BRANCH=CYES,SUP), because SUP is the default 
when YES is coded. Protect key checking is bypassed. 


BRANCH=( YES, PGM) 
Requests the branch entry. You must be authorized by APF 
and be in problem state. Protect key checking is bypassed. 


Requests the SVC entry. You must be authorized by APF if 
any output operations are requested. Protect key checking 
is performed. 


MF: SPECIFY THE FORM OF THE MACRO 


This Keyword specifies whether the list, execute, or normal form 
of the macro is requested. 


If I is coded or if neither L nor E is coded, the CVAF 
parameter list is generated and CVAF is called. This is 
the normal form of the macro. 


MF=L 
L indicates the list form of the macro. A parameter list 
is generated, but CVAF is not called. 


MF=(E,addr) 
E indicates the execute form of the macro. The CVAF 
parameter list whose address is in ‘addr' can be modified 
by this form of the macro. 


RETURN CODES FROM THE CVAFDIR MACRO 


On return from CVAF, register 1 contains the address of the CVPL 
CCVAF parameter list), and register 15 contains one of the 
following return codes: 


Code Meaning 


00CX'00') The request was successful. However, if the CVAFDIR 
request is to read or write a DSCB and a VTOC index 
structure error 18s encountered, the CVSTAT field 
indicates the structure error encountered. CCVSTAT 
code descriptions are in Appendix C, "VTOC Index Error 
Message and Associated Codes™ on page 221.) 


04€X'04') An error occurred. The CVSTAT field in the CVPL 
contains an indication of the cause of the error. 
CCVSTAT code descriptions are in Appendix C, "VTOC 
Index Error Message and Associated Codes" on 
page 221.) 


08CX'08')D Invalid VTOC index structure while processing a 
request to read or write a VTOC index record. The 
CVSTAT field in the CVPL contains an indication of the 
cause of the error. (CCVSTAT code descriptions are in 
Appendix C, "VTOC Index Error Message and Associated 
Codes" on page 221.) 
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12C€X*0C*) The CVAF parameter list is not in your protect key or 
is invalid (the ID is invalid, or the length field is 
incorrect, or the CVFCTIN field is invalid). The CVPL 
has not been modified. 


16C(X*10") An IZ0 error was encountered. 
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CVAFDSM MACRO 


( OVERVIEW OF THE CVAFDSM MACRO 
The CVAFDSM macro may be used for an indexed VTOC to: 


e Obtain one or more extents that describe unallocated space 
on the volume 


e Obtain a count of free DSCBs on the VTOC 


e Obtain a count of free VTOC index records in the VTOC index. 


SYNTAX 


[label] CVAFDSM | ACCESS=MAPDATA 
» MAP= INDEX| VOLUME | VTOC 
[,EXTENTS=addr] 
eS ee 


UCB=(reg) | DEB=addr] 
COUNT=YES!/NO] 


; TOAREA=KEEP | (KEEP, addr ) |NOKEEP | 
(NOKEEP, 

BRANCH=NQIVES=| (VES, SUP) | (YES, PGM)] 

MF=ZILI(CE,addr)] 





[ 
[> 
[> 
4 » CTAREA=addr] 
[> 
[> 


L Default if MF=I. 
_ 2 Default if MF=L or MF=CE,addr). 
( 3 Default is SUP if YES is coded. 


ACCESS=MAPDATA: REQUEST INFORMATION FROM THE INDEX SPACE MAPS 


ACCESS=MAPDATA 
btains data from the index space maps. Three Kinds of 
data are available: 


® The number of format-0 DSCBs (the data is obtained from 
the VTOC map of DSCBs) 


e The number of unallocated VIRs in the index (the data 
is obtained from the VTOC index map) 


6 The number Cand location) of extents of unallocated 
pack space (the data is obtained from the VTOC pack 
space map) 


MAP: IDENTIFY THE MAP TO BE ACCESSED 


MAP=INDEX 
Specifies that the VTOC index map (VIXM) is to be accessed 
and a count of unallocated VIRs returned. COUNT=YES must 
also be coded. 


MAP=VOLUME 
Specifies that the VTOC pack space map CVPSM) is to be 
accessed and information on unallocated extents of pack 
nan las returned. EXTENTS=addr and COUNT=NO must also be 
coded. 


MAP=VTOC 
Specifies that the VTOC map of DSCBs (VMDS) is to be 
accessed and a count of format~0 DSCBs returned. COUNT=YES 
must also be coded. 
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EXTENTS: IDENTIFY WHERE EXTENTS FROM THE VPSM ARE RETURNED 


EXTENTS=addr | 
If one or more extents from the VPSM are requested, EXTENTS 
is the address of a l-byte count field containing the 
number of 5-byte extents that follow. In the first two 
bytes of the first 5-byte extent, you must supply the 
relative track address (RTA) at which CVAF should start the 
VPSM search. The first extent area is updated with 
information on the next free extent found that has a higher 
starting RTA than that supplied. Each subsequent extent 
area is filled in with information on free space extents 
Cin ascending track address order). 





Information on free extents has the format, XXYYZ, where: 


e XX is the relative track address of the first track of 
the extent. | 


® YY is the number of whole cylinders in the extent. 
@ Zis the number of additional tracks in the extent. 


Only XX is supplied by the caller in the first extent area. 
CVAF will start searching the VPSM at relative track 
address XX. 


If all the unallocated extents in the VPSM are provided 
before filling in all the supplied extent areas, the 
remaining extent areas are set to zero. Register 15 is set 
to 4 on return, with the CVSTAT field in the CVPL set to 
X*20* to indicate end of data. 


MAPRCDS: KEEP OR FREE MAPRCDS BUFFER LIST AND BUFFERS 


MAPRCDS=YES — 


\ 
{ 


Specifies that the buffer list and buffers are to be Go 
retained at the end of the function. | 


If YES is specified and no buffer list is supplied through 
the CVAF parameter list, CVAF will read the MAP VIRs into 
buffers obtained by CVAF. The buffer list that contains 
the address and RBAs of the VIRsS can be accessed after the 
CVAF call from the CVAF parameter list field, CVMRCDS. The 
buffer list and VIR buffers are in the caller's protect 
key: subpool 0 if the caller is not authorized; subpool 229 
1f the caller is authorized. 


YES is the default if MF=I is specified or defaulted. 


When processing on the current volume is finished, release 
all areas that were Kept. | 


MAPRCDS=(YES,addr ) 
If YES is coded, but the buffer list address (CVMRCDS in 
CVAF parameter list) 1s supplied, the VIRsS are not read. 


The CVMRCDS buffer list from one CVAF call can be passed to 
another CVAF macro call through the MAPRCDS keyword. 


MAPRCDS=NO 
If MAPRCDS=NO is coded, the MAP records buffers and buffer 
list will be freed upon completion of the CVAFDSM function. 


NO is the default if MF=L is specified. 
MAPRCDS=(NO,addr) 


Causes buffer lists and buffers previously obtained by CVAF 
to be freed. 





186 MVS/XA System-Data Administration 














Buffer lists and buffers obtained by CVAF must be freed by the 
caller. This can be done in one of three ways: 


( | ° By coding MAPRCDS=NO on the call that obtained the buffers. 
7 e By coding MAPRCDS=NO on a subsequent CVAF call. 


@ By calling CVAFDIR ACCESS=RLSE and providing the buffer list 
in the BUFLIST keyword. 


If MF=CE,addr) is coded and MAPRCDS is not coded, the 
parameter list value of MAPRCDS is not changed. 


Note: You must enqueue the VTOC and reserve the unit to 
maintain the integrity of the MAP records read. 


| UCBIDEB: SPECIFY THE VTOC TO BE ACCESSED 


UCB=(req) 
Supplies the address of the UCB for the unit whose VTOC is 
to be accessed. An unauthorized caller may not supply a 
UCB to CVAF. 


Note: Code the address of the UCB parameter only as 
register (2-12). Coding an RX-Type address here gives you 
unpredictable results. 


DEB=addr 
Specifies the address of a DEB opened to the VTOC you want 
to access. CVAF does not allow output requests to the VTOC 
or VTOC index if you specify the DEB subparameter. If you 
are not authorized, you cannot perform any asynchronous 
activity Csuch as EXCP, CLOSE, EOV) against the data set 
represented by the DEB because CVAF removes the DEB from 
_ | the DEB table for the duration of the CVAF call. If you 
i are not authorized (neither APF authorized nor in a system 
key), you must specify a DEB address, not a UCB, to 
CVAFDSM. See "Identifying the Volume™ on page 26 for 
further details. 


If you supply a previously obtained CVAF I/0 area through the 
IOAREA keyword, you need not specify the UCB or DEB keyword. 
Otherwise you must specify either the UCB or DEB keyword. If 
you specify a UCB, the UCB address in the CVPL is overlaid by 
the UCB address in the I/0 area. 


If you supply both the UCB and DEB addresses in the CVPL, CVAF 
uses the DEB address and overlays the UCB address in the CVPL 
with the UCB address in the DEB. 


COUNT: OBTAIN A COUNT OF UNALLOCATED DSCBS OR VIRS 


COUNT=YES 
Indicates that a count of unallocated DSCBs or VIRs in the 
designated space map is requested. MAP=VTOC or MAP=INDEX 
must be specified if COUNT=YES is coded. 


COUNT=NO_ ; 
Indicates that a count of unallocated DSCBs or VIRs is not 
desired but, rather, information on free space on the pack 
is desired. MAP=VOLUME must be coded if COUNT=NO is coded 
or defaulted. 
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CTAREA: 





IOAREA: 





BRANCH: 








SUPPLY A FIELD TO CONTAIN THE NUMBER OF FORMAT-0 DSCBS 
 CTAREA=addr 


Gives the address of a 4~byte field to contain the number 
of format-0 DSCBs when COUNT= YES, MAP=VTOC is specified; or 
the number of unallocated VIRs in the VTOC index when 
COUNT=YES, MAP=INDEX is specified. 


KEEP OR FREE THE I/O WORK AREA 
IOAREA=KEEP 


Specifies that the CVAF I/0 area associated with the CVAF 
parameter list is to be kept upon completion of the CVAF 

request. IOAREA=KEEP may be coded with BRANCH=NO only if 
the caller is authorized CAPF or system Key). 


If IOAREA=KEEP is coded, the caller must issue CVAF with 
IOAREA=NOKEEP specified at some future time, whether or not 
any further VTOC access is required: for example, the 
recovery routine of the caller of CVAF. 


Coding IOAREA=KEEP allows subsequent CVAF requests to be 
more efficient, as certain initialization functions can be 
bypassed. Neither DEB nor UCB need be specified when a 
previously obtained CVAF I/O area is supplied; neither can 
they be changed. 


When IOAREA=KEEP is first issued, CVAF returns the CVAF I/0 
area in the CVAF parameter list (CVIOAR)D. Subsequent calls 
of CVAF may use that same parameter list, and CVAF will 
obtain its I/0 area from the CVIOAR. 


When processing on the current volume is finished, release 
all areas that were kept. 


TOAREA=( KEEP, addr ) 


Provides the address of a previously obtained I[/0 area. If 
a different CVAF parameter list is used, the previously 
obtained CVAF I/0 area may be passed to CVAF by coding its 
address as the second parameter of the IQAREA keyword. 


=NO : 
Causes the work area to be freed upon completion of the 
CVAF request. 


LTOAREA=(NOKEEP,> addr ) 


Causes a previously obtained work area to be freed upon 
completion of the CVAF request. 


SPECIFY THE ENTRY TO THE MACRO 
BRANCH=CYES, SUP } 


Requests that the branch entry to CVAFDIR be used. The 
caller must be in supervisor state. Protect key checking 
is bypassed. 


An 18-word save area must be supplied if BRANCH=YES is 
coded. No lock may be held on entry to CVAF. SRB mode is 
not allowed. 


BRANCH=YES 


Is equivalent to BRANCH=C(YES,SUP), because SUP is the 
default when YES is coded. Protect key checking is 
bypassed. 


BRANCH=CYES, PGM } 


Requests the branch entry. The caller must be APF 
authorized and in problem state. Protect key checking is 
bypassed. 
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MF 








Requests the SVC entry. The caller must be APF authorized 
if any output operations are requested. Protect key 
checking is performed. 


SPECIFY THE FORM OF THE MACRO 


This Keyword specifies whether the list, execute, or normal form 
of the macro is requested. 


If I is coded or if neither L nor E is coded, the CVAF 
parameter list is generated, as is code, to call CVAF. 
This is the normal form of the macro. 


MF=L 
L indicates the list form of the macro. A parameter list 
is generated, but code to call CVAF is not generated. 


MF=(E,addr) 
E indicates the execute form of the macro. The remote CVAF 
parameter list supplied as ‘addr' is used in, and can be 
modified by, the execute form of the macro. 


RETURN CODES FROM THE CVAFDSM MACRO 


On return from CVAF, register 1 contains the address of the CVPL 
CCVAF parameter list), and register 15 contains one of the 
following return codes: 


Code Meaning 
0¢00) The request was successful. 


4(04) End of data CCVSTAT is set to decimal 32), or an error 
was encountered. The CVSTAT field in the CVPL contains 
an indication of the cause of the error. CCVSTAT code 
descriptions are in Appendix C, "VTOC Index Error 
Message and Associated Codes™ on page 221) 


8008) Invalid VTOC index structure. CVSTAT contains an 
indication of the cause of the error. CCVSTAT code 
descriptions are in Appendix C, "VTOC Index Error 
Message and Associated Codes™ on page 221) 


12¢€0C) The CVAF parameter list is not in your protect key or 
is invalid (the ID is invalid, or the length field is 
incorrect, or the CVFCTN field is invalid). The CVPL 
has not been modified. | 


16¢€10) An I/0 error was encountered. 
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CVAFSEQ MACRO 


OVERVIEW OF THE CVAFSEQ@ MACRO 


SYNTAX 











The CVAFSEQ macro may be used to: 


e the an indexed VTOC sequentially in data-set-name CDSN) 
order 


° Read an indexed VTOC or a nonindexed VTOC in 
physical-sequential order 


[label] CVAFSEQ ACCESS=GT|GTEQ 
{,»BUFLIST=addr] 
[,DSN=addr]1 
[,UCB=( req) | DEB=addrl1 
C» DSNONLY=NO|YES] 
[> ARG=addr] 


[, TOAREA=KEEF | (KEE addr) INOKEEP| 
(NOKEEP, addr )] 

[»IXRCDS= KEEP IL CKEEP addr.) | NOKEEP | 
(NOKEEP,addr)] 

4 BRANCH=NO| YES? | (YES, SUP) | (YES,PGH)) 

[)MF=IIL| (E,addr)] 





1 If YES, default is SUP. 


ACCESS: SPECIFY RELATIONSHIP BETWEEN SUPPLIED AND RETURNED DSN 


a 
ACCESS=GT |] 
Specifies that the DSN or argument value is to be used to ee 
Sea DSCB whose DSN or argument is greater than that 
supplied. 


ACCESS=GTEQ 
Specifies that the DSN or argument value is to be used to 
return a DSCB whose DSN or argument is greater than or 
equal to that supplied. 


Note: A CVAF call specifying ACCESS=GTEQ should be 
followed by an ACCESS=GT request, or the same DSCB or name 
will be returned. 


BUFLIST: SPECIFY ONE OR MORE BUFFER LISTS 


BUFLIST=addr: 
The BUFLIST Keyword supplies the address of a buffer list 
used to read or write DSCBs and VIRs. 


| DSN: SPECIFY ACCESS BY DSN ORDER OR BY PHYSICAL-SEQUENTIAL ORDER 


DSN=addr 
Specifies that access of an indexed VTOC is by DSN order. 
BUFLIST is required if DSNONLY=NO is coded or defaulted. 


DSN omitted . 
If you omit the DSN keyword, access of an indexed or 
nonindexed VTOC is by physical-sequential order. BUFLIST 
is required. 


Note: If the order is physical-sequential, you must initialize 
the argument field in the first buffer list entry to zero or to 
the argument of the DSCB. If the argument is zero (BFLEARG=00), 
the read begins at the start of the VTOC. You must be authorized 
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CAPF or system key) to read multiple DSCBs with the CVAFSEQ 
macro. See "Initiating Physical~Sequential Access™ on page 33 
for more information. 


SPECIFY THE VTOC TO BE ACCESSED 


UCB=(req) 
Supplies the address of the UCB for the unit whose VTOC is 
to be accessed. An unauthorized caller may not supply a 
UCB to CVAF. | 


Note: Code the address of the UCB parameter only as 
register (2-12). Coding an RX-Type address here gives you 
unpredictable results. 


DEB=addr 
Specifies the address of a DEB opened to the VTOC you want 
to access. CVAF does not allow output requests to the VTOC 
or VTOC index if you specify the DEB subparameter. If you 
are not authorized, you cannot perform any asynchronous 
activity (Csuch as EXCP, CLOSE, EOV) against the data set 
represented by the DEB because CVAF removes the DEB from 
the DEB table for the duration of the CVAF call. If you 
are not authorized (neither APF authorized nor ina system 
ae lg must specify a DEB address, not a UCB, to 


If you supply a previously obtained CVAF I/0 area through the 
IOAREA keyword, you need not specify the UCB or DEB Keyword. 
Otherwise you must specify either the UCB or DEB keyword. If 
you specify a UCB, the UCB address in the CVPL is overlaid by 
the UCB address in the I/O area. 


If you supply both the UCB and DEB addresses in the CVPL, CVAF 
uses the DEB address and overlays the UCB address in the CVPL 
with the UCB address in the DEB. 


SPECIFY THAT ONLY THE DATA SET NAME BE READ 


This Keyword is applicable only to accessing an indexed VTOC in 
DSN order. 


DSNONLY=NO 
Requests that the data set name be obtained from the VTOC 
index and the DSCB be read into a buffer supplied through 
the BUFLIST keyword. BUFLIST is required. 


DSNONLY=YVES 
Requests that only the data set name be obtained from the 
VTOC index. If the ARG Keyword is coded, the argument of 
the DSCB is returned. 


SPECIFY WHERE THE ARGUMENT OF THE DSCB IS TO BE RETURNED 


This keyword is applicable only to accessing an indexed VTOC in 
DSN order with DSNONLY=YES coded. 


ARG=addr 
Provides the address of the 5-byte area where the CCHHR of 
each data set name in the VTOC index is returned when 
DSNONLY=YES is coded. 
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ITOAREA: 


_IXRCDS: 








KEEP OR FREE THE I70 WORK AREA 
7 IOAREA=KEEP 


Specifies that the CVAF I/0 area associated with the CVAF 
parameter list is to be kept upon completion of the CVAF 
request. IQAREA=KEEP may be coded with BRANCH=NO only if 
the caller is authorized CAPF, or system Key). 


If IOAREA=KEEP is coded, the caller must issue CVAF with 
IOAREA=NOKEEP specified at some future time, whether or not 
any further VTOC access is required: for example, the 
recovery routine of the caller of CVAF. 


Coding IOAREA=KEEP allows subsequent CVAF requests to be 
more efficient, because certain initialization functions 
can be bypassed. Neither DEB nor UCB need be specified 
when a previously obtained CVAF I/0 area is supplied; 
neither can they be changed. 


When IOAREA=KEEP is first issued, CVAF returns the CVAF I70 
area in the CVAF parameter list C(CVIOAR). Subsequent calls 
of CVAF may use that same parameter list, and CVAF will 
obtain its I/0 area from the CVIOAR. | 


When processing on the current volume is finished, release 
all areas that were kept. 


ITOAREA=( KEEP,» addr ) 
Provides the address of a previously obtained I/0 area. If 
a different CVAF parameter list is used, the previously 
obtained CVAF I/0 area may be passed to CVAF by coding its 
address as the second parameter of the IOAREA Keyword. 


Causes the work area to be freed upon completion of the 
CVAF request. 


ITOAREA=(NOKEEP, addr ) 
Causes a previously obtained work area to be freed upon 
completion of the CVAF request. 


RETAIN VIERS IN VIRTUAL STORAGE 


This keyword applies to an indexed VTOC only. 


IXRCDS=KEEP 
Specifies that the VIERs read into storage during the CVAF 
function are to be Kept in virtual storage. The VIERs are 
retained even if the index function is unsuccessful. The 
VIERs are accessed from the CVAF parameter list CCVIRCDS). 
CVIRCDS is the address of a buffer list containing the VIR 
buffer addresses and RBAs of the VIERS read. 


Index search function will dynamically update the buffer 
last and, when necessary, obtain additional buffer lists 
and chain them together. 


If KEEP is specified and no buffer list is supplied to CVAF 
in the CVPL, CVAF will obtain a buffer list and buffers and 
read the first high-level VIER. The address of the buffer 
list is placed in the CVIRCDS field of the CVPL. The first 
high-level VIER will be checked for the VXFHLV bit and to 
see if the VXVISE bit is off. 


The buffer list and VIR buffers are in the caller's protect 
Key. The subpool is 0 if the caller is not authorized; 
subpool 229 if the caller is authorized. 


If IXRCDS=KEEP for an nonindexed VTOC, a request to read a 
DSCB may be performed, but an error code will be returned. 


When processing on the current volume is finished, release 
all areas that were kept. 
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IXRCDS=(KEEP,addr ) 
The CVIRCDS from one CVAF call can 6 Saeeea to another 
CVAF parameter list by specifying the address as the second 
parameter in the IXRCDS keyword. 





If NOKEEP is coded, the VIERs that are accessed (if any) 
are not retained. Furthermore, the buffer list supplied in 
the CVIRCDS field in the CVAF parameter list is released, 
as are all buffers found in the buffer list. If the skip 
bit is set in any entry in the buffer list, the buffer and 
buffer list will not be freed. 


IXRCDS=(NOKEEP, addr ) 
Specifies that previously accessed VIERs are not to be 
retained. 


You must free buffer lists and buffers obtained by CVAF. This 
can be done in one of three ways: 


e By coding IXRCDS=NOKEEP on the CVAFSEQ macro that obtained 
the buffers 


® By coding IXRCDS=NOKEEP on a subsequent CVAF macro 


e By coding CVAFDIR ACCESS=RLSE and providing the address of 
the buffer list in the BUFLIST Keyword 


Note: You must enqueue the VTOC and reserve the unit to 
maintain the integrity of the VIERSsS read. 


BRANCH: SPECIFY THE ENTRY TO THE MACRO 


BRANCH=(YES, SUP) 
a Requests that the branch entry to CVAFDIR be used. The 
— caller must be in supervisor state. Protect key checking 
: 1s bypassed. 


An 18-word save area must be supplied if BRANCH=YES is 
coded. No lock may be held on entry to CVAF. SRB mode is 
not allowed. 


BRANCH=YES 
Is equivalent to BRANCH=CYES,SUP), because SUP is the 
default when YES is coded. Protect key checking is 
bypassed. 


BRANCH=(YES, PGM) : 
Requests the branch entry. The caller must be APF 
authorized and in problem state. Protect key checking is 
bypassed. 


=NO 

Requests the SVC entry. The caller must be APF authorized 
if any output operations are requested. Protect key 
checking is performed. 


MF: SPECIFY THE FORM OF THE MACRO 


This keyword specifies whether the list, execute, or normal form 
of the macro is requested. 


ME=I 
If I is coded, or neither L nor E is coded, the CVAF 
parameter list is generated, as is code, to call CVAF. 
This is the normal form of the macro. 


MF=L 
| L indicates the list form of the macro. A parameter list 
sh | is generated, but code to call CVAF is not generated. 
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MF=(E,addr) 


E indicates the execute form of the macro. The remote CVAF 


parameter list supplied as ‘addr' is used in and can be 
modified by the execute form of the macro. 


RETURN CODES FROM THE CVAFSEQ MACRO 


On return from CVAF, register 1 contains the address of the CVPL 
CCVAF parameter list), and register 15 contains one of the 
following return codes: 


Code 
OOCX*'00') 
04€X'04") 


O8CX'08*) 


12¢0X'0C") 


16€X'10") 


Meaning 
The request was successful. 


End of data CCVSTAT is set to decimal 32), or an error 
was encountered. The CVSTAT field in the CVPL ; 
contains an indication of the cause of the error. 
Error descriptions are in Appendix C, "VTOC Index 
Error Message and Associated Codes™ on page 221 


Invalid VTOC index structure. CVSTAT contains an 
indication of the cause of the error. Error 
descriptions are in Appendix C, "VTOC Index Error 
Message and Associated Codes" on page 221 


The CVPL CCVAF parameter list) is not in your protect 
key, or 1S invalid (the ID is invalid, or the length 

field is incorrect, or the CVFCTN field is invalid). 

The CYPL has not been modified. 


An I70 error was encountered. 
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CVAFTST MACRO © 


( | OVERVIEW OF THE CVAFTST MACRO 


The CVAFTST macro determines whether the system supports an 
indexed VTOC, and, if it does, whether the VTOC on the unit 
whose UCB is supplied is indexed or nonindexed. 


You will get a return code of 12 if CVAFTST cannot determine 
whether an indexed or nonindexed VTOC is on the unit's volume. 
You should not receive a return code of 12 from CVAFTST if you 
have opened a data set Cincluding the VTOC) on the volume. 


You need no authorization to issue the CVAFTST macro. 


SYNTAX 
[label] CVAFTST | UCB=(reqg) 


UCB: SPECIFY THE VTOC TO BE TESTED 


UCB=( req) 
Supplies the address of the UCB for the volume whose VTOC 
1s to be tested. 


Note: Code the address of the UCB parameter only as 
register (2-12) Coding an RX-Type address here gives you 
unpredictable results. 


( ~~ RETURN CODES FROM THE CVAFTST MACRO 


On return from CVAF, register 15 contains one of the following 
return codes: 


Code Meaning 


0¢00) The system does not support an indexed VTOC. The 
volume should be considered to have a nonindexed VTOC. 
The UCB was not inspected to determine its validity or 
status. 


4004) The system supports an indexed VTOC, but the volume has 
a nonindexed VTOQOC. 


808) The system supports an indexed VTOC and the volume has 
an indexed VTOC. 


12¢€0C) The system supports an indexed VTOC, but the volume is 
not mounted or the VIB is not initialized for it; thus, 
the status Cindexed or nonindexed) of the VTOC cannot 
be determined. 


16¢€10) The system supports an indexed VTOC, but the unit is 
not a DASD or has a VIO UCB, or the UCB address is 
invalid. 
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The examples that follow are partial assembler listings that 
include expansions of each VTOC access macro. The expansions 
are provided to show how the VTOC macros can be substituted for 
existing procedures. 


Sa al- APUILN MALKRY WLin AN NUEARD UR NUN“LNVEAGYL e 


This example uses the CVAFDIR macro to read a DSCB of a given 
data set name and determines whether the DSCB is for a 
partitioned data set. The address of the 44-byte data set name 
is supplied to the program in register 5 (labeled RDSN in the 
example). The address of a DEB open to the VTOC is supplied to 
the program in register 4 (labeled RDEB in the example). 


The buffer list is in the program and is generated by the 
ICVAFBFL macro. The DSCB buffer is in the program and is 
generated by the IECSDSL1 macro. 


EXAMPLE1 CSECT 
STM 14,12,12¢CRSAVE) 
BALR 12,0 
USING *,12 
ST RSAVE, SAVEAREAt+4 
LA RWORK, SAVEAREA 
ST RWORK, 8C,RSAVE) 
LR RSAVE, RWORK 
HEHE HEHEHE HE HE HEHE HE HE HEHE HE HE HE HEHE HEHE HEH HH HEHE HEHEHE HE HEHE HEHE HEHE HEHE HE HE HEHE HEHE HEHE HEHE HE HE HEHE HEHE HK HEHEHE HE 


x 
X REGISTERS 
% : 
HE HE HE HE HE HE HE HE HE HE HE HE HE HE HE HE HE HE HEHE CHE HK HEHE HEHE HEHE HE HE HE HEHE HEHE HEHE HE HE HEHE HK HE HEHE HEHE HEHE HEHE HEHE HEHE HH 
REG1 EQU. it REGISTER 1 
RWORK EQU) 3 WORK REGISTER 
RDEB EQU) 4 DEB ADDRESS 
RDSN EQU] 5 ADDRESS OF DATA SET NAME 
RSAVE EQU) 13 SAVE AREA ADDRESS 
REG15 EQU) 15 RETURN CODE REGISTER 15 
HEHE HE HEHE HE HEHE HEHE EH HE HEHEHE H HEHE HEHE HEHEHE HEHE HEHEHE HEHE HEHEHE HH HEHEHE HEHEHE HEHE HHH HH HHH HEM HH HK KH 
2 
BS RETURN CODES 
x 
H HE HE HEHE HE HEHE HEHE HE HE HE HE HEHE HEHEHE HEHEHE HEHE HE HE HE HE HE HE HE HE HE HEHE HEHE HE HEHE HEHE HEH HEH HE HEHE HEHEHE HH HHH HEHEHE 
PDSRTN EQU- QO DATA SET A PDS RETURN CODE 
NOTFND EQU) 4G DATA SET NOT FOUND RETURN CODE 
NOTPDS EQU- 8 DATA SET NOT A PDS RETURN CODE 
UNEXPECD EQU) 12 UNEXPECTED ERROR RETURN CODE 


HE HE HE HEHEHE HK HEHE HEHE HE HEHE HE HE HE HE HE HE IE HE HE HE HE HE HE HE DE HE HE HE HE DE DE DE DE HE HE HE DE HEHEHE HEHE HE HE HH HE HH HK HHH HH HK 


* READ DSCB INTO DSIFMTID. 

¥ DATA SET NAME ADDRESS SUPPLIED IN RDSN. 

* ADDRESS OF DEB OPEN TO VTOC SUPPLIED IN RDEB. 

* DETERMINE IF DATA SET IS A PARTITIONED DATA SET. 
X 
X 
x 


K 


THIS PROGRAM IS NEITHER REENTRANT NOR REUSABLE. 


HE HE HE HE HE HE DE DE HE HE HE HE HE HE DE HE DE DE HE HE HE HE HEHE DE HE HE HE HEHE HE HEHE HEH HEHE HHH HE HH HHH HEH HEH HH HEH HEH HHH 
XC BUFLISTCBFLHLN+BFLELN),BUFLIST ZERO BUFFER LIST 


Ol BFLHFL,BFLHDSCB DSCBS TO BE READ WITH BUFFER LIST 
MVI BFLHNOE,1 ONE BUFFER LIST ENTRY 
LA RWORK, DS1IFMTID ADDRESS OF DSCB BUFFER 
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ST RWORK, BFLEBUF 
OI BFLEFL, BFLECHR 
MVI BFLELTH, DSCBLTH 


MVC DS1DSNAM, OCRDSN)D 





PLACE IN BUFFER LIST 

CCHHR OF DSCB RETURNED BY CVAF 

DATA PORTION OF DSCB READ - DSN % 
SUPPLIED IN CVPL 

MOVE IN DATA SET NAME TO WORKAREA 


CVAFDIR ACCESS=READ, DSN=DS1DSNAM, BUFLIST=BUFLIST, DEB=(RDEB) 


CNOP 0,4 

BAL 1,ICV1E 
Icv1s EQU ¥ 

DC CL4*CVPL' 


DC AL2ZCICVLE-ICV1S) 
DC XL1'O1' 

DC XL1*0O! 

DC B*00000000' 
20000000" 


) 
SI1DSNAM) 
FLIST) 


3B 
H* 
AC0 
ACD 
ACBU 
AC0) 
ACO) 
ACO) 
DC AC0) 
AC0) 
AC0) 
ACO) 
AC0) 
AC0) 
ACO) 
x 


ICVIE 
RDEB, 36(,1) 
OVC 139 

USING CVPL,REG1 
LTR REG15,REGI5 


LOAD CVPL LIST ADDRESS 

START OF CVPL 

EBCDIC ‘CVPL* 

LENGTH OF CVPL 

FUNCTION CODE 

STATUS INFORMATION 

FIRST FLAG BYTE 

SECOND FLAG BYTE 

RESERVED 

UCB ADDRESS 

DATA SET NAME ADDRESS 

BUFFER LIST ADDRESS 

INDEX VIR'S BUFFER LIST ADDRESS 
MAP VIR'S BUFFER LIST ADDRESS 
I7Q AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 
EXTENT TABLE ADDRESS 

NEW VRF VIXM BUFFER LIST ADDR 
VRF DATA ADDRESS 

COUNT AREA ADDRESS 

END OF CVPL 

STORE DEB PTR IN PARM LIST 


ADDRESSABILITY TO CVPL 
ANY ERROR : 
BRANCH IF NOT. 


HEHE HE HE HE HE IE HE HE IE HE HE HE HE HEHE HEHEHE HE HE HEE HE HEHE HH HEHEHE HE HE HE HE HEHEHE HEH HEHE HE HEE HEHEHE HHH HEH HHH HK HK 


NOERROR 
% 
¥ DETERMINE WHAT ERROR IS 
x 


DE HE HE IE IE IE HE IE IE DE DE DE DE HE DE DE IE DE DE DE DE DE DE DE HE DE DE DE IE DE FE DE DE DE DE HE DE DE DE DE DE DE DE DE IE DE DE DE HK DE DE DE DE DE DE DE DE DE EE 


C REG15, ERRORS 
BNE OTHERERR 


IS RETURN CODE 4 

BRANCH IF NOT 4 

IS IT DATA SET NAME NOT FOUND? 
BRANCH IF NOT 

ADDRESSABILITY TO CVPL NOT NEEDED 


H HEHE HEHEHE HE HE HE DE HE IE DE DE JE HE HE HE HE HE HE DE HE IE HE EE HE HE DE HE DE DEE HE HE HE HEHEHE HEHEHE DEE HK HK HHH HHH HHH HKHKK 


CLI CVSTAT,STATOOL 

BNE OTHERERR 

DROP REGI 
x 
¥ DATA SET NAME NOT FOUND 
X 


HHH HEHEHE HEHEHE HEHE HEHEHE HEHEHE HEHEHE HEH THEI HE HEHE HHH HEHEHE HEHE HEHEHE HEI HEHEHE HEHEHE HI IIIT IEIEIE 


L RSAVE,4(C,RSAVE) 
RETURN (14, 12), RC=NOTFND 


LM 14,12,12(13) 
LA 15,NOTFNDCO, 03 
BR 14 
NOERROR EQU xX 
MVC FICCHHR, BFLEARG 
CLI DSIFMTID,C*4' 
BE NOTF1 
TM DS1DSORG, DS1DSGPO 
BO PDS 
NOTF1 EQU x 
L RSAVE,4(€,RSAVE) 
RETURN €14,12),RC=NOTPDS 
LM 14,12,12€13) 


SET UP DATA SET NOT FOUND ERROR 
RESTORE THE REGISTERS 
LOAD RETURN CODE 


| RETURN 
DSCB READ 
MOVE CCHHR OF FORMAT 174 DSCB TO ¥ 
WORKAREA 
IS DSCB A FORMAT 4 DSCB 
BRANCH IF YES. NOT A FORMAT 1 
IS FORMAT 1 DSCB FOR PARTITIONED % 
DATA SET 
BRANCH IF PDS 
DSCB IS NOT A PDS 


SET UP NOT PDS RETURN CODE 
RESTORE THE REGISTERS 
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+ LA 15,NOTPDS(CO0,0) 
+ BR 14 | 
PDS EQU xX 


L RSAVE,4(C,RSAVED 
RETURN (€14,12),RC=PDSRIN 


+ LM 14,12,12(13) 

+ LA 15,PDSRINCO,0) 

+ BR s«dLG 

OTHERERR EQU) xX 

L RSAVE,4(C,RSAVE) 
RETURN (€14,12),RC=UNEXPECD 

+ LM 14,12,12¢€13) 

+ LA 15,UNEXPECD(0, 0) 

+ BR 14 


ERROR DC Frq' 
BUFLIST ICVAFBFL DSECT=NO 


DATA SET IS PARTITIONED 
SET UP PDS RETURN CODE 


RE 
UNEXPECTED ERROR 





LOAD RETURN CODE 
RETURN | 


RESTORE THE REGISTERS 
LOAD RETURN CODE 
TURN 


RESTORE THE REGISTERS 
LOAD RETURN CODE 
RETURN 9 


ERROR RETURN CODE 4 
BUFFER LIST 


HK HEHE DEH HE HEHE HE HE HE HEE HE DE DE HE EK HEHE HE HE HE DE DE DEH HE HE DE HEHE HE HE HE DE DEE HEE HEHE HE DE HE EDC HE HE HK HE HEHEHE HEHEHE HE HEHE HEH HHH HK HHH HK 


+X BUFFER LIST HEADER 


HHH HHH HEH HK HEHE HK HEH HEHE HEHEHE HE HK HE HHH HK HHH HHH HH HK HH HH K HHH HHH HH HHH HK HHH HK HK H RAK KKK KKK KKHKK. 


+BUFLIST DS OF 
+BFLHNOE DS XL1 
+BFLHFL DS XL1 
+ ORG BFLHFL 
+BFLHKEY DS XL1 


+BFLHVIR EQU X'08! 
+BFLHDSCB EQU X'04! 
+ DS XL1 


+BFLHSP DS XL1 
+BFLHFCHN DS A 
+X 


+BFLHLN EQU *¥-BUFLIST 


BUFFER LIST HEADER 
NUMBER OF ENTRIES 
KEY AND FLAG BYTE 


PROTECT KEY CFIRST 4 BITS) 

BUF. LIST ENTRIES DESCRIBE VIRS 
BUF. LIST ENTRIES DESCRIBE DSCBS 
RESERVED 

SUBPOOL OF BUF. LIST/BUFFERS 
oe CHAIN PTR TO NEXT BUF. 
LENGTH OF BUFFER LIST HEADER 


HK HEHE HEHE HK HE HE HE HE HEHE HE HE HE HE HE HEE HE HE DE DEK HE DE HE HEHEHE HE HEHE HEHEHE HEHEHE HK HH HEH HHH HH HH HH HHH HHH HH KH HK KKK HK KKK 


+X BUFFER LIST ENTRY 


HH HE HE HEHE HE DE HE HE HEHEHE HE HE HE HEHE HE HE HE HEHE HEHE DE HE HE HEHE HEHE HE HE HEHE HE HE HE HE HE IE DE HE HE HE HE HE DE HEH HEHE HE HE HE HE HE HE HE HE HE HE HEHE EE HEH HHH ae 
+BFLE DS OF BUFFER LIST ENTRY weed 
+BFLEFL DS XL1 BUFFER LIST ENTRY FLAG 

+BFLERBA EQU' X"™80° ARGUMENT IS RBA 

+BFLECHR EQU  X'*'40! ARGUMENT IS CCHHR 

+BFLETTR EQU  X*20' ARGUMENT IS TTR 

+BFLEAUPD EQU) X"10° CVAF UPDATED ARGUMENT FIELD 

+BFLEMOD EQU X*08! DATA IN BUF. HAS BEEN MODIFIED 

+BFLESKIP EQU X04" SKIP THIS ENTRY 

+BFLEIOER EQU  X*02' I70 ERROR 

+ DS XL1 RESERVED 


+BFLELTH DS AL1 
+X 


+BFLEARG DS AL5 
+ ORG BFLEARG+t] 
+BFLEATTR DS XL3 
+ ORG BFLEARG+] 
+BFLEARBA DS XL 
+BFLEBUF DS A 
+BFLELN EQU *-BFLE 
IECSDSL1 (1) 


LENGTH OF DSCB BUFFER OR 
LENGTH OF VIR DIVIDED BY 256 
ARGUMENT OF VIR OR DSCB CCCHHR) 


"TTR® OF ARGUMENT 
"RBA' OF ARGUMENT 


BUFFER ADDRESS 
LENGTH OF A BUFFER LIST ENTRY 


FORMAT 1 DSCB DATA SET NAME AND x 


BUFFER 


+IECSDSL1 EQU % 
+ITECSDSF1 EQU TECSDSL1 
+DSIDSNAM DS CL44 
+DSIFMTID DS CL1 
+DSIDSSN DS CL6 
#DS1IVOLSQ DS XL2 
+DSICREDT DS XL3 
+DSLEXPDT DS =—=s XL 
+DSINOEPV DS XL1 
+DSINOBDB DS XL1 
+X 
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FORMAT 1 DSCB 


DATA SET NAME 

FORMAT IDENTIFIER 

DATA SET SERIAL NUMBER 

VOLUME SEQUENCE NUMBER 

CREATION DATE 

EXPIRATION DATE , 

NUMBER OF EXTENTS ON VOLUME 

NUMBER OF BYTES USED IN LAST 
DIRECTORY BLOCK 





























i. 
+DS1SYSCD 
+ 
+DS1DSORG 
+X 
+DS1IDSGIS 
+X 
+DS1DSGPS 
+X 


+DSI1DSGDA 
+DS1DSGCX 
+X 

+X 
+DS1IDSGPO 
+DS1DSGU 
+X 

+X 

+X 

+X 
+DS1DSGG6S 
+DSI1DSGTX 
+DS1DSGTQ 
+X 
+DSLACBM 
+DS1IDSGTR 
+X 

+% 
+DS1RECFM 
+DS1OPTCD 
+DSIBLKL 
+DSILRECL 
+DSIKEYL 


_+DSIRKP 


+DSIDSIND 
+DSISCALO 
+DSILSTAR 
+DSITRBAL 


+ 
+DS1EXT1 
+X 


+% 

+X 

+X 

+DSIEXT2 

+DSLEXT3 

+DSIPTRDS 

+DS1END 
DSCBLTH 
FICCHHR 
SAVEAREA 
CVPL 


DS XL1 
DS CL13 
DS XL7 
DS XL2 
EQU X*80' 
EQU X*40! 
EQU X*20° 
EQU X'10' 
EQU X'08! 
EQU X'04! 
EQU X'02' 
EQU X'OL' 
EQU X'80! 
EQU X'GO! 
EQU X'20°' 
EQU X'10!' 
EQU X*08' 
EQU X'04' 
EQU X'02! 
EQU X*O1' 
DS XL1 
DS XL1 
DS XL2. 
DS XL2 
DS XL1 
DS XL2 
DS XL1 
DS XL4 
DS XL3 
DS XL2 
DS XL2 
DS XL10 
FIRST BYTE 


SECOND BYTE 


FIRST BYTE OF 








RESERVED 

SYSTEM CODE 

RESERVED 

DATA SET ORGANIZATION 
DS1DSORG 

IS ~- INDEXED SEQUENTIAL 
ORGANIZATION 

PS - PHYSICAL SEQUENTIAL 
ORGANIZATION 

DA - DIRECT ORGANIZATION 

CX ~ BTAM OR QTAM LINE GROUP 
RESERVED 

RESERVED 

PO ~ PARTITIONED ORGANIZATION 
U - UNMOVABLE, THE DATA 
CONTAINS LOCATION DEPENDENT 
INFORMATION 


SECOND BYTE oe DS1DSORG 


THIRD - SIXTH BYTES 
SEVENTH - TENTH BYTES 


DS XL10 
DS XL10 
DS XL5 
EQU % 

DS 

DS 13F 
ICVAFPL , 


S ~ GRAPHICS ORGANIZATION 
TX - TCAM LINE GROUP 
TQ - TCAM MESSAGE QUEUE 
RESERVED 
ACCESS METHOD CONTROL BLOCK 
TR - TCAM 3705 
RESERVED 
RESERVED 
RECORD FORMAT 
OPTION CODE 
BLOCK LENGTH 
RECORD LENGTH 
KEY LENGTH 
RELATIVE KEY POSITION 
DATA SET INDICATORS 
SECONDARY ALLOCATION 


Q01A 
a01A 


Q01A 
d01A 
d01A 
QO1A 
O01A 
a01A 


A01A 
OO01A 
d01A 
QO1A 
Q01A 
@01A 
A01A 
A01A 


LAST USED TRACK AND BLOCK ON TRACK 
BYTES REMAINING ON LAST TRACK USED 


RESERVED 
FIRST EXTENT DESCRIPTION 
EXTENT TYPE INDICATOR 
EXTENT SEQUENCE NUMBER 
LOWER LIMIT 

UPPER LIMIT 

SECOND EXTENT DESCRIPTION 
THIRD EXTENT DESCRIPTION 
POSSIBLE PTR TO A 


CCHHR OF DSCB 
SAVE AREA | 
CVPL MAPPING MACRO 


FORMAT 2 OR 3 DSCB 
EQU See ener oun OF DATA PORTION OF DSCB 


+ HEHEHE HE HEHE HE HE HE HE HE HEHEHE HE DE HE HE HE HEHE HE DE HE HE HE HEHE HE DE HE HEHE HE HE HE HE HE HE HE HE HE HE HE HE HE HE HE HE HE HE IE HE HE IE DE DE HE HE DE IE IE HE DEE HE IE HEE HE 
CVAF PARAMETER LIST 
HK HEHE HEHE HEHE HEHE HE HEHEHE HEHE HEHE HEHE HEH HEHE HE HEHEHE HEHE HE HE HE HEHEHE HEH HEHE HEHE HE HE HEHEHE HEHE HEHEHE HE HE HE HE HE HE HE HE HE HE HEHE HEHEHE HEN 


+X 


+CVPL 
+ 


+CVLBL 
+CVLTH 
+CVFCTN 
+CVDIRD 
+CVDIWR 
+CVDIRLS 
+CVSEQGT 
+CVSEQGTE 
+CVDMIXA 
+CVDMIXD 
+CVDMALC 
+CVDMRLS 
+CV DMMAP 
+CVVOL 


DSECT 
DS 


DS 

DS 

DS 

EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


OF 
CL4 
H 
XL1 
X'Ol! 
X'02' 
X'O03' 


X04! 


X*05' 


CVAF PARAMETER LIST 


EBCDIC 'CVPL* 

LENGTH OF CVPL 
FUNCTION BYTE 

CVAFDIR ACCESS=READ 
CVAFDIR ACCESS=WRITE 
CVAFDIR ACCESS=RLSE 
CVAFSEQ ACCESS=GT 
CVAFSEQ ACCESS=GTEQ 
CVAFDSM ACCESS=IXADD 
CVAFDSM ACCESS=IXDLT 
CVAFDSM ACCESS=ALLOC 
CVAFDSM ACCESS=RLSE 
CVAFDSM ACCESS=MAPDATA 
CVAFVOL ACCESS=VIBBLD 
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, 














+CVVRFRD EQU X*0C* CVAFVRF ACCESS=READ 

+CVVRFWR EQU X'OD* CVAFVRF ACCESS=WRITE 

+CVSTAT DS XL1 STATUS peer CSEE LIST 

+ BELOW) 

+CVFLI DS XL1 FIRST FLAG BYTE 

+CV1IVT EQU X'80! INDEXED VTOC ACCESSED 

+CVIIOAR EQU X'G0! IQAREA=KEEP 

+CV1IPGM EQU X*20' BRANCH=CYES, PGM) 

+CVIMRCDS EQU X'10° MAPRCDS=YES 

+CV1IRCDS EQU X*08! IXRCDS=KEEP 

+CVIMAPIX EQU X'04° MAP=INDEX 

+CVIMAPVT EQU X*02' MAP=VTOC 

+CVIMAPVL EQU X*o1' MAP=VOLUME 

+CVFL2 DS XL SECOND FLAG BYTE 

+CV2ZHIVIE EQU X'80! HIVIER=YES 

+CV2VRF EQU X'40! VRF DATA EXISTS 

+CV2CNT EQU X*20' COUNT=YES 

+#CV2RCVR EQU ‘X*10" RECOVER=YES 

+CV2SRCH EQU X'O08' SEARCH=YES 

+tCV2ZDSNLY EQU X'04° DSNONLY=YES 

+CV2VER EQU X'02' VERIFY=YES 

+CV2NLEVL EQU X'01' OUTPUT-NEW HIGHEST LEVEL VIER 
+X CREATED 

+ DS H RESERVED 

+CVUCB DS A UCB ADDRESS 

+CVDSN DS A DATA SET NAME ADDRESS 

+CVBUFL DS A BUFFER LIST ADDRESS | 
+CVIRCDS DS A INDEX VIR'S BUFFER LIST ADDRESS 
+CVMRCDS DS A MAP VIR'S BUFFER LIST ADDRESS 
+CVIOAR DS A I70 AREA ADDRESS 

+CVDEB DS A DEB ADDRESS 

+CVARG DS A ARGUMENT ADDRESS 

+CVSPACE DS A SPACE PARAMETER LIST ADDRESS 
+CVEXTS DS A EXTENT TABLE ADDRESS 

+CVBUFL2 DS A NEW VRF VIXM BUFFER LIST ADDR 
+CVVRFDA DS A VRF DATA ADDRESS _ 
+CVCTAR DS A COUNT AREA ADDRESS | — 
+CVPLNGTH EQU *X-CVPL oe 


+X VALUES OF CVSTAT 
+X( THIS as age THE ICVAFPL MACRO EXPANSION IS NOT SHOWN) 
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EXAMPLE2 CSECT 
STM 











This example uses the CVAFDIR macro to read one or more DSCBs on 
a VTOC. The UCB is supplied to the program in register 4 
Clabeled RUCB). The TTR of each DSCB read is to be returned to 
the caller. This program must be APF authorized. 


The address of a parameter list is supplied to the program in 
register 5 Clabeled RLIST). The parameter list contains one or 
more 3-word entries. The format of each 3-word entry is mapped 
by the LISTMAP DSECT. The first word contains the epee of 
the data set name of the DSCB to be read. The second word 
contains the address of the 96-byte buffer into which the DSCB 
is to be read. The third word contains the address of the 
S-byte TTR of the DSCB read. 


The CVPL is generated by a list form of the CVAFDIR macro at 
label CVPL. The BUFLIST, IXRCDS, IOAREA, and BRANCH keywords 
are coded on the list form of the macro. IXRCDS=KEEP and 
IOAREA=KEEP are coded to avoid overhead if two or more DSCBs are 
to be read. BRANCH=CYES,PGM) is coded in the list form of the 
CVAFDIR macro to cause the CVPL to have the CV1PGM bit set to 
one; this will indicate to CVAF that the caller is authorized by 
APF and not in supervisor state. The execute forms of the 
CVAFDIR macro then specify BRANCH=YES, and not BRANCH=CYES,PGM), 
because the CVI1PGM bit is set in the list form of the macro. 


The CVAFDIR macro with ACCESS=RLSE is coded before the program 
exits in order to release the CVAF I/0 area and the index 
records buffer list. BUFLIST=0 is coded because no 
user-supplied buffer list is to be released; BUFLIST was coded 
on the list form of the CVAFDIR macro and, therefore, is in the 
CVBUFL field of the CVPL. This field must be set to zero for 
the release. | 


14,12,12€13) 

BALR 12,0 

USING *,12 

ST 13,SAVEAREA+4 

LA RWORK, SAVEAREA 

ST RWORK, 8€,13) 

LR 13,RWORK 
HE HE HE HE HE HE HE HE HE HE HE HE HEHE HE HE HE HE HEH HE HEHE HE DE HEH HE HE DE HE HE HE HE HE HE HE HE HE HE HE HE HE HE HE HE HE HE DE HK HE DEH HEHE HH HE HEH 
% REGISTERS 
% 
HEHE HE HEHE HE HE HE HE HE HE HE HEHE HE HE HE HE HEHE HE HE HE HE HE HE HE HE HE HE HE HE IE HE HE HE HE HE IE HE HE HE HE IE DE HE IE IE IE HEN HE IE IE HEE EEE 
RWORK EQU 3 WORK REGISTER 
RUCB EQU] 4 UCB ADDRESS SUPPLIED BY CALLER 
RLIST EQU) 5 ADDRESS OF PARAMETER LIST 
RDSN EQU 6 ADDRESS OF DATA SET NAME 
RTTR EQU 7 ADDRESS OF TTR 


REG15 EQU 


RETURN CODE REGISTER 15 


MEK HE HE HE IE HE HE DE HE DE HE HE DE DE DE DE HE DE HE HE HE DE DE DE DE DE DE HE DE DE DE DE HE DE DE DE DE IE DE DE HE DE DE HE HEHE HE HEE DE HE HE DHE HE HEHE HHH 


WORD 


KOK KOK OK OK OOK OK OK OK OK 


3 


READ DSCB OF DATA SET NAME SUPPLIED. RETURN TTR OF DSCB. 
UCB ADDRESS SUPPLIED IN RUCB. 
ADDRESS OF PARAMETER LIST IN RLIST. 

WORD 1 OF PARAMETER LIST = ADDRESS OF DATA SET NAME 

WORD 2 OF PARAMETER LIST = ADDRESS OF DSCB TO BE RETURNED 
OF PARAMETER LIST = ADDRESS OF TTR TO BE RETURNED 


WORDS 1-3 DUPLICATED WITH THE HIGH ORDER BIT OF 
WORD 3 SET TO ONE FOR LAST ENTRY. 


HEHE HE HEE HE DE HE DE HE HE HE HE HE HE HE HE HE HE HE HE HE HE HE DE HE HE HE HE HE IE HE HE DE HE IE HE IE DE IE HE HE DE IE DE HE HE NE HE IE IE HEHE HK HEHEHE 
USING LISTMAP,RLIST 


ADDRESSABILITY TO PARMLIST 
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GSE EEE ET SRE SOE EEE DTA IO TOTO EES Ve CP A A tt ACC LT TT TE EL ITT TE EE DEE TENET EE OE AL: aR IERIE TRE MOTI DATE TONY OKA UML alas WENT VO GLI SENT TE MATT TO PT TL IE TA A TTS T SE eT ID gg TET Cat TT St ge PSU eameymnmmemnme 











TOPLOOP 


teteettetst 


NOERROR 
RELOOP 


HEE tee tees 


+ + 


BUFLIST 





EQU 
XC 
Ol BFLHFL, BFLHDSCB 
MVI BFLHNOE, 1 

LA RWORK,LISTDSCB 
ST RWORK, BFLEBUF 


Ol BFLEFL,BFLETTR 
MVI BFLELTH, DSCBLTH 


RDSN,LISTDSN 


LOOP FOR EACH DSCB 


BUFLIST(BFLHLN+BFLELN) , BUFLIST ZERO BUFFER LIST 


DSCBS TO BE READ WITH BUFFER LIST 

ONE BUFFER LIST ENTRY 

ADDRESS OF DSCB BUFFER 

PLACE IN BUFFER LIST 

TTR OF DSCB RETURNED BY CVAF 

DATA PORTION OF DSCB READ - DSN x 
SUPPLIED IN CVPL 

ADDRESS OF DATA SET NAME 


L 
Eeoeees DSN=CRDSN) , UCB=CRUCB) , MF=CE,CVPL),BRANCH=YES 


1,CVPL 
oT RUCB,12(,1) 
ST RDSN,16(¢,1) 


L 15,16 

L 15,328(€,15) 

L 15,12¢,15) 

L 15,0¢,15) 

BALR 14,15 
RTTR,LISTTTR 


USING TTRMAP,RTTR 

LTR REG15,REG15 

BZ NOERROR 

a TTR, TTR 
RELOOP 

FQU * 


MVC TTR,BFLEARG 
x 


EQU 

™ LASTLIST,LASTBIT 

LA RLIST,NEXTLIST 

BZ TOPLOOP 

CVAFDIR ACCESS=RLSE, 
ITOAREA=NOKEEP, 
IXRCDS=NOKEEP, 
BUFLIST=0, 
BRANCH=YES, 
MF=CE,CVPL) 

LA 1,CVPL 

MVI 6C1),X*03' 

NI 8€1),B*10110111' 

LA 15,0 

oT 15,20¢,1) 


L 15,16 

L 15,328(,15) 

L 15,12¢€,15) 

L 15,0(€,15) 
BALR 14,15 

L 13, SAVEAREA+4 


RETURN (14,12) 
LM 14,12,12€13) 
BR 14 


ICVAFBFL DSECT=NO 


LOAD PARAMETER REG 1 
STORE UCB PTR IN PARM LIST 
STORE DSN PTR IN PARM LIST 
LOAD THE CVT 
LOAD VS1/VS2 COMMON EXTENSION2 
LOAD THE CVT CVAF TABLE 
LOAD THE CVAF ADDRESS 
BRANCH AND LINK TO CVAF 
ADDRESS OF TTR TO BE RETURNED 
MAP OF TTR 
ANY ERROR 
BRANCH IF NOT 
ZERO TTR INDICATING NO DSCB 
GET NEXT ENTRY 
DSCB READ 
RETURN TTR OF DSCB 
GET NEXT ENTRY 
IS IT LAST ENTRY IN LIST? 
GET NEXT ENTRY 
PROCESS NEXT LIST 
RELEASE CVAF OBTAINED AREAS ¥ 
RELEASE IOAREA x 
RELEASE VIER BUFFER LIST % 
NO USER BUFFER LIST SUPPLIED TO dele 
BRANCH ENTER CVAF 


LOAD PARAMETER REG 1 
SET FUNCTION CODE 
RESET CVAF FLAGS OFF 
GET BUFLIST ADDRESS AND 
STORE BUFLIST PTR IN PARM LIST 
LOAD THE CVT 
LOAD VS1/VS2 COMMON EXTENSION2 
LOAD THE CVT CVAF TABLE 
LOAD THE CVAF ADDRESS 
BRANCH AND LINK TO CVAF 


RESTORE THE REGISTERS 
RETURN 


BUFFER LIST 


H HE HEHEHE HE HEHE HE HE HE HE HE HE HEHE HEHEHE HEHEHE HK HEHE HE HEHEHE HE HEHEHE DE HE HEHEHE HE HE DE HE HE DE DE DEDEDE HE HE DE DE HE HE DE DE DE DE HE DE HE HE DEE HE HEH HEHE 


+X 


BUFFER LIST HEADER 


HHH HHH HK HEH HH HE HEHEHE HK HEHE HK HHH HEH HEHEHE HEH HE HEHE HEHE HE HE HEHEHE HE HE HE_ HE HEE HE DE HE HE HE HEHEHE HE HE HE DE DE DE HE HEHE HE HE HE HE HE HE HEHEHE HK 


+BUFLIST 
+BFLHNOE 
+BFLHFL 

+ 
+BFLHKEY 
+BFLHVIR 
+BFLHDSCB 
+ 


+BFLHSP 
+BFLHFCHN 
+X 
+BFLHLN 


DS OF 

DS XL 

DS XL1 
ORG BFLHFL 
DS XL1 
EQU X*08' 
EQU X*04' 
DS XL1 

DS XL1 

DS A 


EQU X-BUFLIST 


BUFFER LIST HEADER 
NUMBER OF ENTRIES 
KEY AND FLAG BYTE 


PROTECT KEY CFIRST 4 BITS) 

BUF. LIST ENTRIES DESCRIBE VIRS 
BUF. LIST ENTRIES DESCRIBE DSCBS 
RESERVED 

SUBPOOL OF BUF. LIST/BUFFERS 
FORWARD CHAIN PTR TO NEXT BUF. 


LIST 
LENGTH OF BUFFER LIST HEADER 
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tHE HEHE HE DE DE IE HE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE IE DE DE DE DE DE DE HE DE DE IE DE DE DE DE IE DE DE DE SE DE DE DE DE DE HE HE HE HE HE HE HE HE HE HK HE HK HE HE HEHE HK HEN 


+X 


BUFFER LIST ENTRY 


EE HEHEHE IE DE IE IE HE HE HK FE HE KE HE DE HE HE HE HE EE HE KE HE HEE HE HE DE HE DE HE DE HE HE HE HE HE DEE HE HE HE HE DE HE DE HE DE DE HE DE HE HE DE HE HE HE EK HEHEHE HK HH KKK 


+BFLE 
+BFLEFL 
+BFLERBA 
+BFLECHR 
+BFLETTR 
+BFLEAUPD 
+BFLEMOD 
+BFLESKIP 
+BFLEIOER 
+ 


+BFLELTH 
+X 
+BFLEARG 
+ 
+BFLEATTR 
+ 


+BFLEARBA 

+BFLEBUF 

+BFLELN 
SAVEAREA 
LISTMAP 
LISTDSN 
LISTDSCB 


LISTTTR 


LASTLIST 
LASTBIT 


NEXTLIST 
DSCB 


DS 
DS 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
DS 
DS 


DS 


+IECSDSL1 EQU 


+IECSDSF1 
+DSIDSNAM 
+DSIFMTID 
+DSIDSSN 
+DS1VOLSQ 
+DSICREDT 
+DSLEXPDT 
+DSINOEPV 
+DS1INOBDB 
+X 


+ 
+DS1SYSCD 
+ 
+DS1DSORG 
+X 
+DSIDSGIS 
+X 
+DSIDSGPS 
+X 


+DSIDSGDA 
+DS1LDSGCX 
+X 

+X 
+DS1DSGPO 
+DS1DSGU 
+X 

+X 

+X 


EQU 





OF 
XL1 
X'80! 
X'40° 
X*20' 
X*10° 
X'08' 
X'04! 
X*02' 
XL1 
XL1 


XL5 
BFLEARGt1 
XL3 
BFLEARG+1 
XL4 

A 

X-BFLE 
18F 

F 

F 

OF 

x 

X™80! 


AL3 
% 


ECT 
ITECSDSL1 (1) 
X 


ITECSDSL1 
CL44 

CLI 

CL6 

XL2 

XL3 

XL3 


XL1 
XL1 


XL1 
CL13 
XL7 
XL2 


X'80! 
X"G0* 


X*20!' 
X*10° 
X'08° 
X'04' 
X*02' 
X"O1' 


FIRST BYTE OF 





BUFFER LIST ENTRY 

BUFFER LIST ENTRY FLAG 
ARGUMENT IS RBA 

ARGUMENT IS CCHHR 

ARGUMENT IS TTR 

CVAF UPDATED ARGUMENT FIELD 
DATA IN BUF. HAS BEEN MODIFIED 
SKIP THIS ENTRY 

I70 ERROR 

RESERVED 

LENGTH OF DSCB BUFFER OR 
LENGTH OF VIR DIVIDED BY 256 
ARGUMENT OF VIR OR DSCB CCCHHR) 


"TTR" OF ARGUMENT 


FRBA' OF ARGUMENT 

BUFFER ADDRESS 

LENGTH OF A BUFFER LIST ENTRY 
REGISTER SAVE AREA 


ADDRESS OF DATA SET NAME 

ADDRESS OF BUFFER FOR DSCB TO BE ¥ 
RETURNED 

ADDRESS OF TTR OF DSCB TO BE % 
RETURNED 

FIRST BYTE 

LAST ENTRY IN LIST 

REMAINDER OF TTR ADDRESS 

NEXT LIST 


FORMAT 1 DSCB 


DATA SET NAME 

FORMAT IDENTIFIER 

DATA SET SERIAL NUMBER 

VOLUME SEQUENCE NUMBER 

CREATION DATE 

EXPIRATION DATE 

NUMBER OF EXTENTS ON VOLUME 

NUMBER OF BYTES USED IN LAST 
DIRECTORY BLOCK 


RESERVED 

SYSTEM CODE 

RESERVED 

DATA SET ORGANIZATION 

DSIDSORG 

IS - INDEXED SEQUENTIAL @01A 
ORGANIZATION 

PS - PHYSICAL SEQUENTIAL A01A 
ORGANIZATION 

DA - DIRECT ORGANIZATION a01A 
CX - BIAM OR QTAM LINE GROUP a01A 
RESERVED O01A 
RESERVED A01A 
PO - PARTITIONED ORGANIZATION a01A 
U - UNMOVABLE, THE DATA OO01A 
CONTAINS LOCATION DEPENDENT 
INFORMATION 
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+X SECOND BYTE OF DS1DSORG 

+DSIDSGGS EQU X'80!' GS - GRAPHICS ORGANIZATION a01A 
+DSIDSGTX EQU X'40! TX - TCAM LINE GROUP Q01A 
+DSIDSGTQ EQU X*20° TQ - TCAM MESSAGE QUEUE | Q01A 
+X EQU X*10° RESERVED Q01A 
+DS1ACBM EQU X'O8! ACCESS METHOD CONTROL BLOCK Q01A 
+DSIDSGTR EQU X*04' TR -— TCAM 3705 a01A. 
+X EQU X'02° RESERVED — @01A 
+X EQU XfOl* RESERVED a01A 
+DS1RECFM DS XL1 RECORD FORMAT 

+DS1OPTCD DS = XLI OPTION CODE 

+DSIBLKL DS XL2 BLOCK LENGTH 

+#DSILRECL DS XL2 RECORD LENGTH 

+DSIKEYL DS XL1 KEY LENGTH 

+DSIRKP DS XL2 RELATIVE KEY POSITION 

+DSIDSIND DS XL1 DATA SET INDICATORS 

+DSISCALO DS XL4 SECONDARY ALLOCATION 

+DSILSTAR DS XL3 LAST USED TRACK AND BLOCK ON TRACK 
+DSITRBAL DS XL2 BYTES REMAINING ON LAST TRACK USED 











+ DS XL2 RESERVED 
+DSIEXT1 DS XL10 FIRST EXTENT DESCRIPTION 
+X FIRST BYTE EXTENT TYPE INDICATOR 


+X SECOND BYTE EXTENT SEQUENCE NUMBER 
+X THIRD - SIXTH BYTES LOWER LIMIT 
+X SEVENTH ~ TENTH BYTES UPPER LIMIT 


+DS1EXT2 DS XL10 
+DSIEXT3 DS XL10 


SECOND EXTENT DESCRIPTION 

THIRD EXTENT DESCRIPTION 
+DSIPTRDS DS XL5 POSSIBLE PTR TO A FORMAT 2 OR 3 DSCB 
+DSLEND EQU % 


DSCBLTH EQU ¥-DSCB-L'*DS1DSNAM LENGTH OF DATA PORTION OF DSCB 


TTRMAP ~= DSECT 
TTR DS XL3 TTR TO BE RETURNED 


EXAMPLE2 CSECT 


CVPL CVAFDIR ACCESS=READ, BUFLIST=BUFLIST,MF=L, % 
IOAREA=KEEP, KEEP IOAREA TO AVOID OVERHEAD % 
IXRCDS=KEEP KEEP VIERS FOR 2ND AND SUBSEQUENT ie 
CALLED IN PROGRAM STATE BUT APF fo 
AUTHORIZED SO UCB IS SUPPLIED | \ J 
CNOP 0,4 7 Soe” 
+CVPL EQU ¥ 
+ DC CLG*CVPL!* EBCDIC ‘CVPL* 
+ DC AL2CICV8E-CVPL)} LENGTH OF CVPL 
+ DC XL1'OL* FUNCTION CODE 
+ DC XL1*00* STATUS INFORMATION 
+ Dc B'01001000' FIRST FLAG BYTE 
+ DC B'00000000! SECOND FLAG BYTE 
+ DC H'o? RESERVED 
+ DC ACO) UCB ADDRESS 
+ DC AC0) DATA SET NAME ADDRESS 
+ DC ACBUFLIST) BUFFER LIST ADDRESS 
+ DC AC0) INDEX VIR'S BUFFER LIST ADDRESS 
+ DC AC0) MAP VIR'S BUFFER LIST ADDRESS 
+ DC AC0) | I70 AREA ADDRESS 
+ DC ACO) DEB ADDRESS 
+ DC AC0) ARGUMENT ADDRESS 
+ DC AC0) SPACE PARAMETER LIST ADDRESS 
+ DC AC0) EXTENT TABLE ADDRESS 
+ DC AC0) NEW VRF VIXM BUFFER LIST ADDR 
+ DC AC03 VRF DATA ADDRESS 
+ DC AC0) COUNT AREA ADDRESS 
+ICVS8E EQU ¥ 


END OF CVPL 
ORG CVPL OVERLAY CVPL WITH EXPANSION OF MAP 
CVPLMAP ICVAFPL DSECT=NO 
HHH HK HHH HH HEH HHH HH HHH HEHEHE HEHEHE HE HEHE HEHEHE HEHE HEHEHE HEHEHE HEHE HEHEHE HEHEHE HEHEHE HEHE HEHEHE HEHEHE HEH HEHEHE HHH HH HEH 
+X CVAF PARAMETER LIST 
He HEHEHE HEHE HE HEHE HE HEH HE HE HE HE HEHE HE HE HE HE HE HE HE IE HE HE HE HE DE HE IE IE HE DE HE HEHE HE DE IE IE HE IE HE HE IE DE DE DE DE DE HE IE HE IE DE DE DE DE DE IE DE DE HE DE DE IE DEEN 


+CVPLMAP DS OF CVAF PARAMETER LIST 
+CVLBL DS CL4 EBCDIC ‘*CVPL* 
+CVLTH DS H LENGTH OF CVPL 
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+CVFCTN 
+CVDIRD 
+CVDIWR 
+CVDIRLS 
+CVSEQGT 
+CVSEQGTE 
+CVDMIXA 
+CVDMIXD 
+CVDMALC 
+CVDMRLS 
+CVDMMAP 
+CVVOL 
+CVVRFRD 
+CVVRFWR 
+CVSTAT 
+- 


+CVFLI 
+CVLIVT 
+CVIIOAR 
+CV1PGM 
+CVIMRCDS 
+CV1IRCDS 
+CVIMAPIX 
+CVIMAPVT 
+CVIMAPVL 
+CVFL2 
+CV2HIVIE 
+CV2VRF 
+CV2CNT 
+CV2RCVR 
+CV2SRCH 
+CV2DSNLY 
+CV2VER 
+CV2NLEVL 
+X 


+ 
+CVUCB 


— +#CVDSN 


+CVBUFL 
+CVIRCDS 
+CVMRCDS 
+CVIOAR 
+CVDEB 
+CVARG 
+CVSPACE 
+CVEXTS 
+CVBUFL2 
+CVVRFDA 
+CVCTAR 
+CVPLNGTH 


DS XL1 
EQU X*O1' 
EQU X*02' 
EQU X'03! 
EQU X'04! 
EQU X'0O5! 
EQU X'06' 
EQU X*0O7' 
EQU X'08! 
EQU X'09! 
EQU X*OA* 
EQU X* OB! 
EQU X'0Cc* 
EQU X*OD* 
DS XL1 
DS XL1 
EQU X80! 
EQU X*40' 
EQU X*20' 
EQU X*10° 
EQU X'08! 
EQU X'04! 
EQU X'02' 
EQU X*O1' 
DS XL1 
EQU X*80° 
EQU X*40' 
EQU x'*20° 
EQU X‘10! 
EQU X'08! 
EQU X*04! 
EQU X*02' 
EQU X*Ol' 
DS H 
DS A 
DS A 
DS A 
DS A 
DS A 
DS A 
DS A 
DS A 
DS A 
DS A 
DS A 
DS A 

A 


DS 


EQU *x-CVPLMAP 
VALUES OF CVSTAT 





ptt ant Nenad atenennanmlamatna sntttcttnnnt Laem tletneeh mbite Ao Ldeee ent ten tn 


FUNCTION BYTE 
CVAFDIR ACCESS=READ 
CVAFDIR ACCESS=WRITE 
CVAFDIR ACCESS=RLSE 
CVAFSEQ ACCESS=GT 
CVAFSEQ ACCESS=GTEQ 
CVAFDSM ACCESS=IXADD 
CVAFDSM ACCESS=IXDLT 
CVAFDSM ACCESS=ALLOC 
CVAFDSM ACCESS=RLSE 
CVAFDSM ACCESS=MAPDATA 
CVAFVOL ACCESS=VIBBLD 
CVAFVRF ACCESS=READ 
CVAFVRF ACCESS=WRITE 
STATUS INFORMATION CSEE LIST x 
BELOW) 

FIRST FLAG BYTE 
INDEXED VTO0C ACCESSED 
TOAREA=KEEP 
BRANCH=CYES,PGM) 
MAPRCDS=YES 
IXRCDS=KEEP 

MAP=INDEX 

MAP=VTOC 

MAP=VOLUME 


SECOND FLAG BYTE 


HIVIER=YES 

VRF DATA EXISTS 

COUNT=YES 

RECOVER=YES 

SEARCH=YES 

DSNONLY=YES 

VERIFY=YES 

OUTPUT-NEW HIGHEST LEVEL VIER 
CREATED 

RESERVED 

UCB ADDRESS 

DATA SET NAME ADDRESS 

BUFFER LIST ADDRESS 

INDEX VIR'S BUFFER LIST ADDRESS 
MAP VIR'S BUFFER LIST ADDRESS 
I70 AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 
EXTENT TABLE ADDRESS 

NEW VRF VIXM BUFFER LIST ADDR 
VRF DATA ADDRESS 

COUNT AREA ADDRESS 


+X(THIS ar THE ICVAFPL MACRO EXPANSION IS NOT SHOWN) 





AEraichiaracti*eint taisutar uaa danas ane seniinbabinim meiiinadi emma ee eRaineR PASTE Ot RGR ANOS SI PA NOE A AM LSPS MEE TT PE ATMO 
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ee 


ENG HE CVAFSEQ MACRO WITH AN INDEXED OC 


This example uses the CVAFSEQ macro to count the number of ISAM 
data sets whose data set names are within the range defined by 
two supplied data set names. The addresses of the two data set 
names are supplied to the program in registers 6 and 7, labeled. 
RDSN1 and RDSN2, respectively. The address of a DEB open to the 
VTOC is supplied in register 4%, labeled RDEB. 





The CVAF parameter list is expanded by a list form of the 
CVAFSEQ@ macro. ACCESS=GTEQ is specified on the list form of the 
macro and is, therefore, not coded in the first execution of the 
CVPL. Subsequent executions of the CVPL Cat label RELOOP) 
specify ACCESS=GT. 


End of data is tested by comparing the CVSTAT field to the value 
of STAT032, which is an equate in the ICVAFPL mapping macro. 


The count of ISAM DSCBs matching the data set name criterion is 
returned in register 15, unless an error is enccuntered, in 
which case a negative 1 is returned in register L5. 


EXAMPLES CSECT 
STM 14,12,12013) 


BALR 12,0 

USING *,12 

ST 13, SAVEAREA+4 
LA RWORK, SAVEAREA 
ST RWORK, 8C€,13) 


13,RWORK 

HE HE HE HE HE HE HEE HE DE HEE DE DE DE DE 3E EDC DE DE DE DE DEE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DHE HE HEHE HE HEHE HK HK 

X 

x REGISTERS 

X 

HEH HE HE HE HEE HE HE HE HE HE HE HE HE IE IE IE HE DE DE DE HE HE IE IE HE HE HE HE HE HE HE HEH HE HE HE DE HE HE HEHE HEHEHE HH HEHE HE HE HEH HH HK HK 

REG] EQU 1 REGISTER 1 = 
RWORK EQU) 3 WORK REGISTER _— 
RDEB EQU DEB ADDRESS oy 
RDSN1 EQU 6 ADDRESS OF DATA SET NAME 1 = 
RDSN2  EQU 7 ADDRESS OF DATA SET NAME 2 

REG1I5  EQU_ 15 RETURN CODE REGISTER 15 


KKH HK KH HHH KH KH HH HK HK HK HH HH HK HH HH HH HK KKH K HK KK KKK KKK KKK KK KKK KKKKK 


% COUNT THE NUMBER OF ISAM DATA SETS WHOSE DATA SET NAMES ARE 
* BETWEEN DSN1 AND DSN2 INCLUSIVELY. 

x RDSN1 CONTAINS ADDRESS OF DSNI. 

x RDSN2 CONTAINS ADDRESS OF DSN2. 

% ADDRESS OF DEB OPEN TO VTOC SUPPLIED IN RDEB. 

x 
x 


HE HE HE HE HE HE HE HE HE HE HE HE HE HE HE HE HE HE HE HE DE HE HE HE IE HE HE HEHE HE HE HE HE HE HE HE HE HE HEHE HE HE HE HE HE DE HE HE HE HE HE HE HE IE HC HE HEHE 
_ XC BUFLISTCBFLHLN+BFLELN)D,BUFLIST ZERO BUFFER LIST 


OI BFLHFL, BFLHDSCB DSCBS TO BE READ WITH BUFFER LIST 

MVI BFLHNOE,1 ONE BUFFER LIST ENTRY 

LA RWORK, DSLFMTID ADDRESS OF DSCB BUFFER 

oT RWORK, BFLEBUF PLACE IN BUFFER LIST 

MVI BFLELTH,DSCBLTH DATA PORTION OF DSCB READ - DSN ¥ 


| SUPPLIED IN CVPL 
MVC DS1DSNAM, OCRDSNI) MOVE IN STARTING DATA SET NAME TO % 


WORKAREA 
XR RWORK, RWORK ZERO COUNT 
CVAFSEQ DEB=CRDEB), FIND FIRST DATA SET WHOSE DATA SET xX 
BUFLIST=BUFLIST, NAME IS GREATER THAN OR EQUAL TO % 
MF=CE,CVPL) THAT OF DSNI1 
+ LA 1,CVPL LOAD PARAMETER REG 1 
+ ST RDEB, 36(,1) STORE DEB PTR IN PARM LIST 
+ SVC 139 
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LOOP EQU xX LOOP UNTIL END OF DATA OR DATA SET X 
| NAME GREATER THAN DSN2 


ais USING CVPL,REGI ADDRESSABILITY TO CVPL 
( LTR REGI5,REGI5 ANY ERROR 
BZ. TESTDSN BRANCH IF NOT-CHECK DSN LIMIT 
HE HE HE EE DE DE DE DE DE DE DE DEE DE DE DEDEDE HE DE DE DE DE DE DE DE NE SE SE HE DE DE NE DE EE EE EK EE HE EE DE HEE HE DE HE HE DEE HE EK 
X* 
% DETERMINE WHAT ERROR IS 
¥ 
C  _REG15, ERRORG IS RETURN CODE 4 
BNE OTHERERR BRANCH IF NOT 4 
CLI CVSTAT, STATO32 IS IT END OF DATA? 
BNE OTHERERR BRANCH IF NOT 
DROP REGI ADDRESSABILITY TO CVPL NOT NEEDED 
HH HH HHH HHH HEHEHE HHH HK HH HH HK HH HHH HH HEH HEHE HEHE KKH HK RHE HHRHMHMHKK 
¥% 
% END OF DATA 
xX 
HH HEHE DHE HE HE HE HE HE HEHEHE HEHEHE HK HEHEHE HK HH HHH HH HEHEHE HH HK HHH HK HHH HHH HH HHH KKH 
B ~-RELEASE RELEASE CVAF RESOURCES AND RETURN 
TESTDSN EQU x . IS DATA SET NAME GREATER THAN DSN2 
CLI DSIFMTID,C'l® IS THIS A FORMAT 1 DSCB? 
BNE CKLAST BRANCH IF NO. CAN NOT BE ISAM. 
CLC DSIDSNAM,OCRDSN2) HAS LIMIT BEEN REACHED? 
BNH TESTIS BRANCH IF NO-TEST FOR ISAM 
B —s*RELEASE RELEASE CVAF RESOURCES AND RETURN 
TESTIS EQU x ONLY COUNT ISAM 
T™  DSIDSORG,DSIDSGIS | IS DATA SET ISAM 
BZ  CKLAST BRANCH IF NO-DO NOT COUNT IT 
LA RWORK,1(,RWORK) INCREMENT COUNT BY ONE 
CKLAST EQU x | CHECK IF LAST DATA SET NAME C(DSN2) 
CLC DSIDSNAM,OC(RDSN2) HAS LIMIT BEEN REACHED? 
BNH RELOOP BRANCH IF NO-READ NEXT ONE 
B_ RELEASE RELEASE CVAF RESOURCES AND RETURN 
: RELOOP EQU READ NEXT DSCB 
aan CVAFSEQ ACCESS=GT,MF=(E,CVPL) GET DSCB WITH DATA SET NAME % 
( GREATER THAN THE ONE LAST READ 
+ LA —s-1, CVPL LOAD PARAMETER REG 1 
+ MVI 6(€1),X"04! SET FUNCTION CODE 
+ SVC 139 
B  +LOOP CHECK RESULTS OF CVAFSEQ 
OTHERERR EQU x UNEXPECTED ERROR 
HK KH HH HHH HH HK HHH HK HHH HHH HH HH HHH HHH KH KKH HHH HK KH HMHKHHRKKRHRKRRK 
¥* 
x UNEXPECTED ERROR PROCESSING 
* 
HEH HEH HE HE HEHE DE DE DE DE HK HE DEK HK DHE HE HEE DE HE DE DE DEE HE SE EEE EEE EE HERE EERIE HEE HEE KHKKMRH RHR 
LA RWORK,1(0,0) ONE IN RWORK 
LNR RWORK,RWORK SET NEGATIVE COUNT INDICATING ERROR 
RELEASE CVAFDIR ACCESS=RLSE, RELEASE CVAF BUFFERS/IOAREA % 
BUFLIST=0, DO NOT RELEASE USER BUFFER LIST % 
IXRCDS=NOKEEP, RELEASE CVAF VIER BUFFERS % 
MF=C(E>CVPL) RELEASE CVAF I/0 AREA 
+RELEASE EQU x 
+ LA «1, CVPL LOAD PARAMETER REG 1 
+ MVI 6(1),X"03" SET FUNCTION CODE 
+ NI  8C€1),B"11110111! RESET CVAF FLAGS OFF 
+ LA —s-:15,0 GET BUFLIST ADDRESS AND 
+ ST  15,20C,1) STORE BUFLIST PTR IN PARM LIST 
+ SVC 139 | 
LR REG15, RWORK CURRENT COUNT IS RETURN CODE 
13, SAVEAREA+4 
RETURN (14,12),RC=(15) | RETURN CURRENT COUNT 
+ L 16,12(13,0) RESTORE REGISTER 14 
+ LM  0,12,20(13) RESTORE THE REGISTERS 
+ BRO RETURN 
ERRORG DC FtG! ERROR RETURN CODE 4 
BUFLIST ICVAFBFL DSECT=NO BUFFER LIST 
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Ce coe e cece arr FETT Bho [FUT Ee LEN Te TE TT EE EGET EI FTI EE TEE Ee BE TTD See OT SE EE EC CSCIC EERE LEE LL 











HEE HEHE DE DE IE HE DE HE HE HE DE DE HE DE DE DE HE DE HE DE HE HE HE IE HE HE IE DE DE DE DE DE DE DE HE DE DE IE DE HE DE DE DE HE HE IE TE DE DE HE DE DE HE DE DE DE HE HEHEHE HE HEHE HEE HK HHH 


+X 


BUFFER LIST HEADER 


eK HEHE HE HEHE HEHE HE DE HE DE DE HE HE DE DE HEE HEE HEHE HEHEHE HE HK HE HE HE HE DE HEHEHE HE HE HEHE DE DE HE IE HE HE DE HE HE HE DEE HE HE HE DE HE DE HEHE DE HE NH HEH HEN HN 


+BUFLIST 
+BFLHNOE 
+BFLHFL 
+ 


+BFLHKEY 
+BFLHVIR 
+BFLHDSCB 
—- 


+BFLHSP 
+BFLHFCHN 
+X 


+BFLHLN 


DS 
DS 
DS 


ORG 


DS 
EQU 
EQU 
DS 
DS 
DS 


EQU 


OF 

XL1 
XL1 
BFLHFL 
XL1 
X'08! 
X'04! 
XL1 
XL1 

A 


*-BUFLIST 


BUFFER LIST HEADER 
NUMBER OF ENTRIES 
KEY AND FLAG BYTE 


PROTECT KEY CFIRST 4 BITS) 

BUF. LIST ENTRIES DESCRIBE VIRS 
BUF. LIST ENTRIES DESCRIBE DSCBS 
RESERVED 

SUBPOOL OF BUF. LIST/BUFFERS 
aoe CHAIN PTR TO NEXT BUF. 


LENGTH OF BUFFER LIST HEADER 


# HEHE HEHE HE HE HE HE HE HE HE HE HK DE HE HE DE DE HE DE HE DE HE HE HE HE DE HE DE IE DE HE DE HE DE IE IE HE HE IE HE DE DE IE IE DE HE HE IE HE IE IE DE DE DE HE HE HE IE HE HE HE HE HE HEHE IE HEHEHE IE 


+X 


BUFFER LIST ENTRY 


EK HEHE HK HEHEHE H HEH HEHE HEHEHE HE HEHE HEHE HEHEHE HE HE HEHEHE HK HH HEH HEH HEHEHE HEHEHE EH HK HEH HEHEHE HEH HH HH HEH HH HHH KH KH KKK 


+BFLE 
+BFLEFL 
+BFLERBA 
+BFLECHR 
+BFLETTR 
+BFLEAUPD 
+BFLEMOD 
+BFLESKIP 
+BFLEIOER 


+ 
+BFLELTH 
+X 
+BFLEARG 
+ 
+BFLEATTR 
+ 
+BFLEARBA 


+BFLEBUF 
+BFLELN 


+ITECSDSL1 
+IECSDSF1 
+DS1DSNAM 
+DS1FMTID 


— +DSIDSSN 


+DSIVOLSQ 
+DSICREDT 
+DSLEXPDT 
+DSINOEPV 
+DSLNOBDB 
+X 


af 
+DSISYSCD 
+ 
+DS1DSORG 
+X 
+DSIDSGIS 
+X 
+DS1DSGPS 
+X 
+DSIDSGDA 
+DSIDSGCX 


+X 
+X 


DS OF 
DS XL1 
EQU X'80° 
EQU X*40° 
EQU X*20!° 
EQU X*10!° 
EQU X'08! 
EQU X'04' 
EQU X'02! 
DS XL1 
DS XL1 
DS XL5 
ORG BFLEARGt1 
DS XL3 
ORG BFLEARGt1 
DS XL4 
DS A 
EQU *X-BFLE 
IECSDSLI (1) 
EQU % 
EQU IECSDSLI1 
DS CL44 
DS CL1 
DS CL6 
DS XL2 
DS XL3 
DS XL3 
DS XLI 
DS XL1 
DS XL1 
DS CL13 
DS XL7 
DS XL 
EQU X* 
EQU X'40' 
EQU X*20' 
EQU X*10! 
EQU X*08' 
EQU X'04' 


2 
py FIRST BYTE OF 


BUFFER LIST ENTRY 

BUFFER LIST ENTRY FLAG 
ARGUMENT IS RBA 

ARGUMENT IS CCHHR 

ARGUMENT IS TTR 

CVAF UPDATED ARGUMENT FIELD 
DATA IN BUF. HAS BEEN MODIFIED 
SKIP THIS ENTRY 

I70 ERROR 

RESERVED 

LENGTH OF DSCB BUFFER OR 
LENGTH OF VIR DIVIDED BY 256 
ARGUMENT OF VIR OR DSCB CCCHHR) 


"TTR® OF ARGUMENT 


*RBA* OF ARGUMENT 

BUFFER ADDRESS 

LENGTH OF A BUFFER LIST ENTRY 
FORMAT 1 DSCB DATA SET NAME AND 
BUFFER 
FORMAT 1 DSCB 


DATA SET NAME 

FORMAT IDENTIFIER 

DATA SET SERIAL NUMBER 

VOLUME SEQUENCE NUMBER 

CREATION DATE 

EXPIRATION DATE 

NUMBER OF EXTENTS ON VOLUME 

NUMBER OF BYTES USED IN LAST 
DIRECTORY BLOCK 


RESERVED 

SYSTEM CODE 

RESERVED 

DATA SET ORGANIZATION 

DS1DSORG 

IS - INDEXED SEQUENTIAL Q01A 
ORGANIZATION 

PS - PHYSICAL SEQUENTIAL d01A 
ORGANIZATION 

DA ~ DIRECT ORGANIZATION a01A 
CX - BTAM OR QTAM LINE GROUP d01A 
RESERVED AQ01A 
RESERVED A01A 
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+DS1DSGPO0 
+DS1DSGU 
+X 

+X 

+X 

+X 
+DS1DSGGS 
+DS1DSGTX 
+DSIDSGTQ 
+X 
+DS1ACBM 
+DSIDSGTR 
+% 

+X 
+DSIRECFM 
+DSIOPTCD 
+DSIBLKL 
+DSILRECL 
+DSIKEYL 
+DS1RKP 
+DSIDSIND 
+DSISCALO 
+DSILSTAR 
+DSITRBAL 
+ 


+DSLEXT1 
+% 


+DSLEXT2 
+DSIEXTS 
+DSIPTRDS 
+DSITEND 
DSCBLTH 
SAVEAREA 
CVPL 


+ 
QO 
< 
be 9 | 
re 


HHEEEHE EE EE EEE EEE HEHEHE HH 


ICVIOE 


EQU X*02' 
EQU X*‘O1' 
EQU X*80! 
EQU X"G 
EQU X*2 
EQU Xt] 
EQU X*0 
EQU X*0 
EQU X'02' 
EQU X"O1' 
DS XL 
DS XL1 
DS XL2 
DS XL2 
DS XLI 
DS XL2 
DS XL1 
DS XL4 
DS XL3 
DS XL2 
DS XL2 
DS XL10 
FIRST BYTE 


SECOND BYTE 
THIRD - SIXTH BYTES 
a eee BYTES 


DS 
DS XL10 
DS XL5 
EQU 


DS 


F 
CVAFSEQ ACCESS=GTEQ, 
IXRCDS=KEEP, | 
DSN=DS1DSNAM, 


PO ~- PARTITIONED ORGANIZATION d01A 


U - UNMOVABLE, THE DATA a01A 
CONTAINS LOCATION DEPENDENT 
INFORMATION 

SECOND BYTE OF DS1DSORG 
GS - GRAPHICS ORGANIZATION OO1A 
TX - TCAM LINE GROUP d01A 
TQ - TCAM MESSAGE QUEUE O01A 
RESERVED d01A 
ACCESS METHOD CONTROL BLOCK @O1A 
TR - TCAM 3705 Q01A 
RESERVED a01A 
RESERVED a01A 


RECORD FORMAT 

OPTION CODE 

BLOCK LENGTH 

RECORD LENGTH 

KEY LENGTH 

RELATIVE KEY POSITION 

DATA SET INDICATORS 

SECONDARY ALLOCATION | 

LAST USED TRACK AND BLOCK ON TRACK 
BYTES REMAINING ON LAST TRACK USED 
RESERVED 

FIRST EXTENT DESCRIPTION 

EXTENT TYPE INDICATOR 

EXTENT SEQUENCE NUMBER 

LOWER LIMIT 

UPPER LIMIT 

SECOND EXTENT DESCRIPTION 

THIRD EXTENT DESCRIPTION 

POSSIBLE PTR TO A FORMAT 2 OR 3 DSCB 


¥ 
EQU Pi ean LENGTH OF DATA PORTION OF DSCB 


SAVE AREA 


SUPPLIED DATA SET NAME 


BUFLIST=BUFLIST, 


CNOP 0,4 


m 
&) 
, a 
* 


DC CL4'CVPL* 
DC AL2ZCICV1IOE-CVPL ) 
DC ALL*O5* 
DC XL1°OO' 
DC B'00001000' 
DC B'00000000' 
H*o! 


oO 

o>) 
KPPPPYPrrpryp 
PN PRN NIN RES 
eoaoaaooaoooec 
Net Ne a es ee 


ORG CVPL 


AC0) 
DC ACDSIDSNAM) 
AC0) 


=] 

.) 
rP> 
TN ON ON 
oo 
ww 


EBCDIC *CVPL* 
LENGTH OF CVPL 
FUNCTION CODE 
STATUS INFORMATION 
FIRST FLAG BYTE 
SECOND FLAG BYTE 
RESERVED 
UCB ADDRESS 
DATA SET NAME ADDRESS 
BUFFER LIST ADDRESS 
INDEX VIR'S BUFFER LIST ADDRESS 
MAP VIR'S BUFFER LIST ADDRESS 
I7Q0 AREA ADDRESS 
DEB ADDRESS 
ARGUMENT ADDRESS 
SPACE PARAMETER LIST ADDRESS 
EXTENT TABLE ADDRESS 
NEW VRF VIXM BUFFER LIST ADDR 
VRF DATA ADDRESS 
COUNT AREA ADDRESS 
END OF CVPL 
EXPAND MAP OVER LIST 


Appendix B. Examples of VTOC Access Macros 209 





READ DSCB WITH DSN >= SUPPLIED DSN xX 
KEEP VIERS IN STORAGE DURING CALLS xX 














CVPLMAP ICVAFPL DSECT=NO CVPL MAP 


FHA KH HH HHH HEH HEH HH HK HE HEH HH HEHE HEHE HHH HEHEHE NH HH HEHE HEHE HEHE HEHE HEN HE HE HE HE HE HE HE HE HEHEHE NE HE HE NE IE NE HE HE HE HE EE 








+X CVAF PARAMETER LIST 

HEHEHE HEH HHH HEH HEHEHE HEHEHE HEHEHE HE HEHE HEH HE HEHEHE HEH HEHEHE HEME HE HEHEHE HE HEH HEHEHE HE HEH HEHEHE HEHE IE DE NE IE HED DE IE HEHE HEHE HEHEHE IE 
+CVPLMAP DS OF _ CVAF PARAMETER LIST 

+CVLBL DS CL4 EBCDIC 'CVPL' | 

+CVLTH DS H LENGTH OF CVPL 

+CVFCTN DS XL1 FUNCTION BYTE 

+CVDIRD EQU X*ol' CVAFDIR ACCESS=READ 

+CVDIWR EQU X'02' CVAFDIR ACCESS=WRITE 
+#CVDIRLS EQU X*03' CVAFDIR ACCESS=RLSE 

+CVSEQGT EQU X'04' CVAFSEQ ACCESS=GT 

+CVSEQGTE EQU. X*'05' CVAFSEQ ACCESS=GTEQ 

+CVDMIXA EQU X*06° CVAFDSM ACCESS=IXADD 
+CVDMIXD EQU X'07' CVAFDSM ACCESS=IXDLT 
+CVDMALC EQU X*08! CVAFDSM ACCESS=ALLOC 
+CVDMRLS EQU X*09! CVAFDSM ACCESS=RLSE 

+CVDMMAP EQU X*OA' CVAFDSM ACCESS=MAPDATA 
+CVVOL EQU X'OB* CVAFVOL ACCESS=VIBBLD 
+CVVRFRD EQU X*O0C* CVAFVRF ACCESS=READ 

+CVVRFWR EQU X*OD* CVAFVRF ACCESS=HWRITE 

+CVSTAT DS XL1 STATUS INFORMATION CSEE LIST 
+ BELOW) 

+CVFLI1 DS XL1 FIRST FLAG BYTE 

+CVLIVT EQU X*80! INDEXED VTOC ACCESSED 
+CVIIOAR EQU X*GO! IOAREA=KEEP 

+CV1PGM EQU X*20'° BRANCH=CYES, PGM) 

+CVIMRCDS EQU X*10° MAPRCDS=YES 

+CVIIRCDS EQU X'08! IXRCDS=KEEP 

+CVIMAPIX EQU X'04! MAP=INDEX 

+CVIMAPVT EQU X*02' MAP=VTOC 

+CVIMAPVL EQU X'O1' MAP=VOLUME 

+CVFL2 DS XL1 SECOND FLAG BYTE 

+CV2HIVIE EQU X*80! HIVIER=YES 

+CV2VRF EQU X'40° VRF DATA EXISTS 

+CV2CNT EQU X'20! COUNT=YES 

+#CV2RCVR EQU X*10!' RECOVER=YES 

+CV2SRCH EQU X'08! SEARCH=YES 

+#CV2DSNLY EQU X*04' DSNONLY=YES 

+CV2VER EQU X*02'° VERIFY=YES 

+CV2NLEVL EQU X*O1' OUTPUT-NEW HIGHEST LEVEL VIER 
+X CREATED 

+ DS H RESERVED 

+CVUCB DS A UCB ADDRESS 

+CVDSN DS A DATA SET NAME ADDRESS 
+CVBUFL DS A BUFFER LIST ADDRESS 

+CVIRCDS DS A INDEX VIR'S BUFFER LIST ADDRESS 
+CVMRCDS DS A MAP VIR'S BUFFER LIST ADDRESS 
+CVIOAR DS A I7Q AREA ADDRESS 

+CVDEB DS A DEB ADDRESS 

+CVARG DS A ARGUMENT ADDRESS 

+CVSPACE DS A SPACE PARAMETER LIST ADDRESS 
+CVEXTS DS A EXTENT TABLE ADDRESS 
+CVBUFL2 DS A NEW VRF VIXM BUFFER LIST ADDR 
+CVVRFDA DS A VRF DATA ADDRESS 

+CVCTAR DS A COUNT AREA ADDRESS 

+CVPLNGTH EQU *¥-CVPLMAP 7 

+X VALUES OF CVSTAT 


+X( THIS Bao! THE ICVAFPL MACRO EXPANSION IS NOT SHOWN) 
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WU 

















N ie 8 VE 2 Aw 1 A NVNANVEARY : 


This example reads as many as five DSCBs in physical-sequential 
order. The address of the UCB is supplied to the program in 
register 5 Clabeled RUCB). The address of a parameter list is 
supplied in register 4 Clabeled RLIST). The first word of the 
parameter list contains the address of a 5-byte field. On 
entry, this field is set to zero if no previous DSCBs have been 
read; otherwise, the field is set to the CCHHR of the last DSCB 
read. This 5-byte field is supplied by the caller of this 
program and is not modified by this program. 





The remainder of the parameter list consists of one or more 
2-word entries, to a maximum of five 2-word entries. The first 
word of each entry contains the address of a 1940-byte DSCB 
buffer. The second word contains the address of a 5-byte field 
that is to contain the CCHHR of the DSCB. 


A buffer list with five buffer list entries is contained in the 
program. The ICVAFBFL macro generates the buffer list header and 
one buffer list entry. The remaining buffer list entries are 
generated following the ICVAFBFL macro. 


The CVAFSEQ macro is used once in the program to read as many 
DSCBs as there are 2-word entries in the parameter list. The 
buffer list header field BFLHNOE is initialized with the number 
of buffer list entries that CVAFSEQ is to process. The number 
matches the number of 2-word entries in the parameter list 
supplied to this program. 


After the CVAFSEQ call, the CCHHR for each DSCB read is moved 
from the buffer list entry field BFLEARG to the field whose 
address is supplied by the caller of the program. If the 
BFLEARG field is zero, the previous DSCB read was the last in 


the VTOC. 
. The BFLEARG in the first buffer list entry is initialized with 
the CCHHR supplied by the caller: its address is the third word 


in the parameter list. This CCHHR serves as the starting place 
for the CVAFSEQ call. DSCBs with a CCHHR greater than the 
supplied CCHHR are read. 


This program must be APF authorized. 


EXAMPLE4 CSECT 
oTM 


14,12,12€13) 
BALR 12,0 
USING ¥*,12 
ST 13,SAVEAREA+4 


LA RWORK, SAVEAREA 
oT RWORK, 8C€,13) 


13,RWORK 
HEHE DE HE HEHE HE HE IE HE HE HE HE HE HE HE HE DE HE HE DE HE HEHE HEH HE HE HE HE HE HE HE HE HE HEHE HEHE HE IE HE HE HEHE HE HE HE HE HE IE HE IE HEHE HE HE IE 
% 
x REGISTERS 
* 
HEHE HE HE HE IE HE IE HE HE HE CHE HE HE HE IE HE HE HE IE HEHE HE HE HEHE HE IE HE IE HE HEE HEHE HEHE HE HE HE HE HE HE HE HE HK IE HE HEHE IE DE DE HE IE HE EIEN 
REG1 EQU) 1 REGISTER 1 
RWORK EQU] 3 WORK REGISTER 
RLIST EQU) 4 ADDRESS OF PARM LIST 
RUCB EQU 5 UCB ADDRESS 
RCURRENT EQU 6 CURRENT ENTRY IN PARM LIST 
RBLE EQU 7 CURRENT BUFFER LIST ENTRY 
RCOUNT EQU 8 COUNT OF ENTRIES IN BUFFER LIST 
REGI5 FQU) 15 RETURN CODE REGISTER 15 
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3 

% READ UP TO 5 DSCBS. 

% RUCB CONTAINS ADDRESS OF UCB. 

x RLIST CONTAINS ADDRESS OF PARAMETER LIST. 

% WORD 0 = ADDRESS OF CCHHR OF LAST DSCB READ. THIS DSCB IS 
% NOT TO BE READ 7 

% WORD 1 = ADDRESS OF DSCB BUFFER. 

% WORD 2 = ADDRESS OF CCHHR OF DSCB READ. 

¥ WORDI AND WORD2 REPEATED UP TO 4 TIMES. 

% HIGH ORDER BIT OF WORD 2 SET TO ONE FOR LAST ENTRY. 
X 

% 


HEHEHE HE HEHEHE IE HE HE HE HEHE HEHE HE HE HE HE HE HE HE HEH HE HEH IE HE HE HEHE HE HEHE HE HEHE HEHE HE HE HE HE HE HE HEHE HEHE HEHE HEHE HEHEHE EN 
USING LIST,RLIST 7 ADDRESSABILITY TO PARM LIST 
XC BFLHDRCBFLHLN+5XBFLELN),BFLHDR ZERO BUFFER LIST WITH 
5 BUFFER LIST ENTRIES 
OI BFLHFL,BFLHDSCB DSCBS TO BE READ WITH BUFFER LIST 
LA  RCURRENT,LISTPRMS FIRST DOUBLEWORD ENTRY IN PARM LIST 
USING LISTPRMS,RCURRENT USING ON DOUBLEWORDS 


LA RBLE,BFLE FIRST BUFFER LIST ENTRY 
USING BFLE,RBLE 
L RWORK, LISTSTRT ADDRESS OF STARTING CCHHR 
MVC BFLEARG, OCRWORK) MOVE STARTING CCHHR INTO FIRST 
BUFFER LIST ENTRY 
XR RCOUNT, RCOUNT ZERO COUNT 
BUFLOOP EQU x al ADDRESSES IN BUFFER LIST 


LA RCOUNT,1(€,RCOUNT ) INCREMENT COUNT 

L RWORK, LISTBUF ADDRESS OF DSCB BUFFER 

ST RWORK, BFLEBUF-BFLEC,RBLE) PLACE IN BUFFER LIST 

MVI BFLELTH-BFLECRBLE),DSCBLTH FULL DSCB READ 

™ LISTLAST,LASTBIT IS IT LAST ENTRY IN LIST 

LA RCURRENT, LISTNEXT INCREMENT TO NEXT ENTRY IN LIST 

LA RBLE, BFLELNC,RBLE)D INCREMENT TO NEXT BUFFER LIST ENTRY 
BZ BUFLOOP LOOP TO PUT NEXT BUFFER IN BFLE 


STC RCOUNT, BFLHNOE SET NUMBER OF ENTRIES IN BUFFER 
LIST HEADER 
DROP RCURRENT,RBLE 
HEHE HE HEHE HE HE HE HE HEH HEHE HEHEHE HEHE HE HEHE HE HEHEHE HEH HE HEH HE HEH HEHE HEH HHH HEHE HEH HEHEHE HEHEHE HHH HHH HH HH 
x 
x READ UP TO 5 DSCBS WHOSE CCHHR IS GREATER THAN THE CCHHR IN 
% THE FIRST BUFFER LIST ENTRY 
b 3 
HEH HE HEH HE HEHE HEHEHE HEHE HE HEHE HEHE HEHE HE HE HEHEHE HE HE HE HEHE HE HE HE HEHE HEHE HE HEHEHE HE HEHE HE HEHE HEHE HEHE HEHEHE HEH KH 
CVAFSEQ UCB=CRUCB), CALL CVAF 
BRANCH=YES, BRANCH ENTER 
MF=CE,CVPL) 
+ LA 1,CVPL LOAD PARAMETER REG 1 
+ ST RUCB,12C,1) STORE UCB PTR IN PARM LIST 
+ L 15,16 LOAD THE CVT 
+ L 15,328C€,15) LOAD VS1/VS2 COMMON EXTENSION2 
+ L 15,12¢€,15) LOAD THE CVAF TABLE ADDRESS 
+ L 15,0¢€,15) LOAD THE CVAF ADDRESS 
+ BALR 14,15 BRANCH AND LINK TO CVAF 
USING CVPL,REG1 ADDRESSABILITY TO CVPL 
LTR REG15,REGI5 ANY ERROR 
BZ MOVECHR BRANCH IF MOVE IN CCHHRS 
HEHE HE HEHE HE HEHE HEHEHE HEH HEHE HE HEHE HE HEHE HE HEHEHE HE HEHE HEHE HE HEHE HEHE HE HE HEHEHE HEHE HE HEH HEHEHE HEHE HEHEHE HHH HE HHH 
* 
DETERMINE WHAT ERROR IS 
x 


HE HE HE HE HE IE HE HE HK HE HEE DE HE DE HE HE HE HE DE HE DEN HE HE DEE HE HE HE HE HE IE HE HE HE IE HE HE HE IE HE HE HEHE HE HE HE DE IE DE IE HE HE HEHE HEHEHE 
Cc REG15, ERRORS IS RETURN CODE 4 


BNE OTHERERR BRANCH IF NOT 4 

CLI CVSTAT,STATO32 — IS IT END OF DATA? 

BNE OTHERERR BRANCH IF NOT 

DROP REG] ADDRESSABILITY TO CVPL NOT NEEDED 
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aK 




















HE IE HE HEHE HE HE HE HE HE HE FE DE HE HE HE HE HE FE HEHE DE HE HE TE HE HE DE IE DE DE TE IE DE HE IE DE DE IE DE HE DE IE DE IE DE HE TE DE HE E DE IE JE HE JE EEE HE 


x 
ae, x DETERMINE IF ANY DSCBS HAVE BEEN READ. BFLEARG IS NON-ZERO 
( : % IN EACH BUFFER LIST ENTRY FOR WHICH A DSCB HAS BEEN READ 
Lo, X 
: HEH HEHEHE HEHE HE HE HE HEHE HE DE HE HE HE HE HE HE HE HEHE HE HEE DE DE HE DE DE HE HE HE HE HE DE HE HE HE HE DE HE HEHEHE HE DE HE HE HEHE HE HEHEHE HEHE NEE 
MOVECHR EQU x IS DATA SET NAME GREATER THAN DSN2 
LA RCURRENT, LISTPRMS FIRST ENTRY IN PARM LIST 
USING LISTPRMS, RCURRENT 
LA RBLE,BFLE FIRST BUFFER LIST ENTRY 
USING BFLE,RBLE 
CHRLOOP EQU x MOVE CCHHR ARGUMENT TO CALLER AREA 
L RWORK, LISTCHR ADDRESS OF CCHHR OF CALLER 
XC  OCL"*BFLEARG,RWORK),OCRWORK) ZERO CALLER CCHHR AREA 
NC BFLEARG, BFLEARG IS CCHHR ZERO 
BZ EXIT BRANCH IF YES-NO MORE DSCBS 
MVC OCL*BFLEARG,RWORK),BFLEARG MOVE CCHHR TO CALLER AREA 
™  LISTLAST,LASTBIT LAST ENTRY IN PARM LIST? 
BO EXIT BRANCH IF YES 
LA RCURRENT, LISTNEXT NEXT ENTRY IN LIST 
LA  RBLE,BFLELN(,RBLE) NEXT BUFFER LIST ENTRY 
B CHRLOOP TEST NEXT BFLE 
EXIT EQU xX RETURN TO CALLER 
L 13, SAVEAREA+4G 
RETURN (14,12) 
+ LM 14,12,12(13) RESTORE THE REGISTERS 
+ BR 14 RETURN 
OTHERERR EQU x ERROR PROCESSING 
X 
x* 
x 
B EXIT RETURN 
ERRORG DC. FG! RETURN CODE 4 
ICVAFBFL DSECT=NO BUFFER LIST WITH ONE BUFFER LIST x 
| ENTRY 
( H HE KE DE HE HEE DEE IE HE HE HE HE DEE IE DE DE HE DE DE DEE HK DE DE HE DE HE HE HEE ESE DE EE HE EK DE EE HE DE EE DE HEE DE DE IE DE HE EE HEE HEE EE HE HK HEHE HEHE HK 
q +X BUFFER LIST HEADER 
KE HE DEE HE HE IE DE DEE DE DE EEE DE DE EE EE HE EE HK HE HE EE EE HEE DE EE EE HE DE EE HE EEK DE DE HE EE HE DE HE EE HEE EK EE EEK HMMM HK 
+BFLHDR DS OF BUFFER LIST HEADER 
+BFLHNOE DS XL1 NUMBER OF ENTRIES 
+BFLHFL DS XL1 KEY AND FLAG BYTE 
+ ORG  BFLHFL | 
+BFLHKEY DS XL1 PROTECT KEY (FIRST 4 BITS) 
+BFLHVIR EQU  X*'08! BUF. LIST ENTRIES DESCRIBE VIRS 
+BFLHDSCB EQU  X*'04' BUF. LIST ENTRIES DESCRIBE DSCBS 
+ DS XL1 RESERVED 
+BFLHSP DS XL1 SUBPOOL OF BUF. LIST/BUFFERS 
+BFLHFCHN DS A FORWARD CHAIN PTR TO NEXT BUF. 
+X 
+BFLHLN EQU %X-BFLHDR LENGTH OF BUFFER LIST HEADER 
EK HHH HE HK HEH HK HE HH HEHEHE HEHE HIE HE KKH HHH HK HHH EHH HHH HH HK H HHH HHH HHH HHH H HHH KKK HKHKKRKKKRRKNRK 
+X BUFFER LIST ENTRY 
“HK HK HEE HEHE KH KK HE HK HEE EE EE IE EE HK HEHE HE HEE HE EE EE EK HE HK HE KE EE HE HE HE HEE HE HEE HEE HEE HE HEHEHE HHH HHH HH HKHK 
 +BFLE DS OF BUFFER LIST ENTRY 
+BFLEFL DS XL1 BUFFER LIST ENTRY FLAG 
+BFLERBA EQU  X*80! ARGUMENT IS RBA 
+BFLECHR EQU X*'GO! ARGUMENT IS CCHHR 
+BFLETTR EQU  X*'20! ARGUMENT IS TTR 
+BFLEAUPD EQU) X*'10! CVAF UPDATED ARGUMENT FIELD 
+BFLEMOD EQU X*08! DATA IN BUF. HAS BEEN MODIFIED 
+BFLESKIP EQU  X*'04! SKIP THIS ENTRY 
+BFLEIOER EQU X*02! I/O ERROR 
+ DS XL1 RESERVED 
+BFLELTH DS XL1 LENGTH OF DSCB BUFFER OR 
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+ 
+BFLEARG 
+ 


+BFLEATTR 
of. 


+BFLEARBA 
+BFLEBUF 
+BFLELN 


SAVEAREA 
DSCB 


+ITECSDSL1 
+IECSDSF1 
+DS1IDSNAM 
+DS1FMTID 
+DSIDSSN 

+DSIVOLSQ 
+DSICREDT 
+DSIEXPDT 
+DSINOEPV 
_ +DSINOBDB 
+X 


+DS1SYSCD 
+DS1DSORG 
+DS1DSGIS 
+DS1DSGPS 


+DS1DSGDA 
+DS1DSGCX 
+X 

+X 
+DS1DSGPO 
+DS1DSGU 
+X 

+X 

+X 

+X 
+DS1DSGGS 
+DS1DSGTX 
+DSIDSGTQ 
+X 
+DS1LACBM 
+DSIDSGTR 
+X 

+X 
+DS1RECFM 
+DS1OPTCD 
+DSIBLKL 
+DSILRECL 
+DSIKEYL 
+DSI1RKP 
+DSIDSIND 
+DSISCALO 
+DSILSTAR 
+DSITRBAL 


+ 
+DSLEXTI 
+ 


+DSLEXT2 
+DSLEXTS 





DS 
ORG 
DS 
ORG 
DS 
DS 
EQU 
DS 
DS 


DSECT 
IECSDSL1 (1) 


SECOND BYTE 


XL5 


BFLEARG+t] 
XL3 
BFLEARG+1 


XL4 
A 


X-BFLE 
CLCGXBFLELN)D 
138F 





LENGTH OF VIR DIVIDED BY 256 
CCCHHR) 


ARGUMENT OF VIR OR DSCB 
"TTR' OF ARGUMENT 


"RBA' OF ARGUMENT 
BUFFER ADDRESS 


LENGTH OF A BUFFER LIST ENTRY 


FOUR BUFFER LIST ENTRIES 
SAVE AREA 


FORMAT 1 DSCB DATASET NAME AND 
DATA 


FORMAT 1 DSCB 


DATA SET NAME 

FORMAT IDENTIFIER 

DATA SET SERIAL NUMBER 

VOLUME SEQUENCE NUMBER 

CREATION DATE 

EXPIRATION DATE 

NUMBER OF EXTENTS ON VOLUME 

NUMBER OF BYTES USED IN LAST 
DIRECTORY BLOCK 

RESERVED 

SYSTEM CODE 

RESERVED 

DATA SET ORGANIZATION 

DS1DSORG 

IS - INDEXED SEQUENTIAL 

ORGANIZATION 

PS - PHYSICAL SEQUENTIAL 

ORGANIZATION 

DA - DIRECT ORGANIZATION 


CX —- BIAM OR QTAM LINE GROUP 


RESERVED 

RESERVED 

PO - PARTITIONED ORGANIZATION 
U - UNMOVABLE, THE DATA 
CONTAINS LOCATION DEPENDENT 
INFORMATION 


SECOND BYTE “ DS1DSORG 


EQU % 
EQU IECSDSL1 
DS CL44 
DS CL1 
DS CL6 
DS XL2 
DS XL3 
DS XL3 
DS XL1 
DS XL1 
DS XL1 
DS CL13 
DS XL7 
DS XL2 
FIRST BYTE OF 
EQU X*380' 
EQU X*40' 
EQU X*20! 
EQU X*10!' 
EQU X'08'° 
EQU X*04' 
EQU X*02' 
EQU X*Ool* 
EQU X*80 
EQU X*40! 
EQU X*20! 
EQU X?10° 
EQU X'08! 
EQU X*04' 
EQU X'O02! 
EQU X*O1' 
DS XL1 
DS XL1 
DS XL2 
DS AL2 
DS XL1 
DS XL2 
DS ALI 
DS XL4 
DS XL3 
DS XL2 
DS XL2 
DS XL10 
FIRST BYTE 


THIRD - SIXTH BYTES 
SEVENTH - TENTH BYTES 


DS 
DS 


XL10 
XL10 


> ~ GRAPHICS ORGANIZATION 
TX - TCAM LINE GROUP 
TQ —- TCAM MESSAGE QUEUE 
RESERVED 
ACCESS METHOD CONTROL BLOCK 
TR - TCAM 3705 
RESERVED 
RESERVED 
RECORD FORMAT 
OPTION CODE 
BLOCK LENGTH 
RECORD LENGTH 
KEY LENGTH 
RELATIVE KEY POSITION 
DATA SET INDICATORS 
SECONDARY ALLOCATION 


Q01A 
A01A 


201A 
OO01A 
A01A 
d01A 


@01A 


a01A 


Q01A 
Q01A 
A01A 
Q01A 
Q01A 
A01A 
A01A 
d01A 


LAST USED TRACK AND BLOCK ON TRACK 
BYTES REMAINING ON LAST TRACK USED 


RESERVED . 

FIRST EXTENT DESCRIPTION 
EXTENT TYPE INDICATOR 
EXTENT SEQUENCE NUMBER 
LOWER LIMIT 

UPPER LIMIT 

SECOND EXTENT DESCRIPTION 
THIRD EXTENT DESCRIPTION 
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+DSIPTRDS 


+DS1END 
DSCBLTH 
LIST 


LISTSTRT 
LISTPRMS 


LISTBUF 
LISTCHR 


LISTLAST 


LASTBIT 


LISTNEXT 
EXAMPLE4 


XK 
x 
X 
Xx 


CVPL 


htt 
3) 
=< 
0 
r 


BHR EEEEEEEE EEE EES 


ICV6E 
CVPLMAP 


+X 


+CVPLMAP 
+CVLBL 
+CVLTH 
+CVFCTN 
+CVDIRD 
+CVDIWR 
+CVDIRLS 
+CVSEQGT 


+CVSEQGTE 


+CVDMIXA 
+CVDMIXD 
+CVDMALC 
+CVDMRLS 
+CVDMMAP 
#CVVOL 

+CVVRFRD 


DS 


XL5 


EQU ¥ 
EQU %X-IECSDSL1 


DSECT 
DS 
EQU 
DS 

DS 

DS 
EQU 
DS 
EQU 
CSECT 


F 

x 

FE 

OF 

X 
X*80! 
AL3 
x 


CVAFSEQ ACCESS=GT, 


BUFLIST=BFLHDR, 
MF=L 


CNOP 0,4 

EQU % 

DC CL4*CVPL' 
DC AL2CICV6E-CVPL) 
DC XL1°04¢! 

DC XL1*00' 

DC B*00190000' 
DC B*00000000' 
DC H'O! 

DC AC0) 

DC AC0) 

DC ACBFLHDR) 
DC ACO) 

DC ACQ) 

DC ACO) 

DC ACO) 

DC ACQ) 

DC ACQ) 

DC ACO) 

DC AC0) 

DC ACO) 

DC AC0) 

EQU X 

ORG CVPL 


ICVAFPL DSECT=NO 
KKH KH HH HHH HH HK HH HK HK HK HHH HH HK HEH HH HH HHH H HE HEHEHE HHH HH HH HN HEH HHH HH KH HHH HH HK KKK KKRKKK 


CVAF PARAMETER LIST 
EHH HHH HHH HEH HEHEHE HE HEHEHE HEHE DE HE HE HEHE HEHE HEHE HEH HEHE HEHE HEH HE HEHE EH HEHE HEHEHE HEN HEHE HEHE H HEHEHE HEN HH KH HK KKK HH 


CVAF PARAMETER LIST 


DS 

DS 

DS 

DS 

EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


OF 
CL4 
H 

XL1 
X'Ol' 
X'02* 
X'03? 
X*04! 
X'05!' 
X'06' 
X'07'* 
X'08' 
X*09! 
X'OA' 
X'OB! 
X'oct 








accede 





POSSIBLE PTR TO A FORMAT 2 OR 3 DSCB 


LENGTH OF DSCB 
PARAMETER LIST 
ADDRESS OF CCHHR TO START SEARCH 


BUFFER ADDRESS 
ADDRESS OF CCHHR FIELD 


BYTE 
LAST DOUBLE 


WORD 


3 BYTE ADDRESS OF CCHHR 
NEXT DOUBLEWORD 


HEE HHH HHH HK HK KH H HHH HH H_ HHH HE HEHE HEHEHE HE HE HEHEHE HEHE DEE HE DE HEHE IE HEHE DE HEHEHE HEHEHE HE HE HE HE EH HHH 


READ DSCBS WITH CCHHR GREATER THAN THE CCHHR IN THE FIRST 
BUFFER LIST ENTRY. 


HE HE HE HEHE HEHE HE HEHEHE HE HEHEHE DE HEH HEH HE HEHE HK HH HH HH HK HE HEH HEHE HEHEHE HEHEHE HK HE HH HEH HH HHH HHH HK HKX 


ADDRESS OF BUFFER LIST % 


EBCDIC 
LENGTH 


*CVPL* 
OF CVPL 


FUNCTION CODE 


STATUS 


INFORMATION 


FIRST FLAG BYTE 


SECOND 


FLAG BYTE 


RESERVED 
UCB ADDRESS 
DATA SET NAME ADDRESS 


BUFFER 


LIST ADDRESS 


INDEX VIR'S BUFFER LIST ADDRESS 
MAP VIR'S BUFFER LIST ADDRESS | 
I70 AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 


EXTENT 


TABLE ADDRESS 


NEW VRF VIXM BUFFER LIST ADDR 
VRF DATA ADDRESS 
COUNT AREA ADDRESS 
END OF CVPL 
EXPAND MAP OVER LIST 


CVPL MAP 


EBCDIC 


"CVPL* 


LENGTH OF CVPL 
FUNCTION BYTE 


CVAFDIR 
CVAFDIR 
CVAFDIR 
CVAFSEQ 
CVAFSEQ 
CVAFDSM 
CVAFDSM 
CVAFDSM 
CVAFDSM 
CVAFDSM 
CVAFVOL 
CVAFVRF 
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ACCESS=READ 
ACCESS=WRITE 
ACCESS=RLSE 
ACCESS=G6T 
ACCESS=GTEQ 
ACCESS=IXADD 
ACCESS=IXDLT 
ACCESS=ALLOC 
ACCESS=RLSE 
ACCESS=MAPDATA 
ACCESS=VIBBLD 
ACCESS=READ 
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+CVVRFWR 
+CVSTAT 

- 

+CVFL1 
+CVLIVT 
+CV1LIOAR 
+CV1PGM 
+CVIMRCDS 
+CVLIRCDS 
+CVIMAPIX 
+CVILMAPVT 
+CVIMAPVL 
+CVFL2 
+CV2HIVIE 
+CV2VRF 
+CV2CNT 
+CV2RCVR 
+CV2SRCH 
+CV2DSNLY 
+CV2VER 
+CV2NLEVL 
+X 


af. 
+CVUCB 
+CVDSN 
+CVBUFL 
+CVIRCDS 
+CVMRCDS 
+CVIOAR 
+CVDEB 
+CVARG 
+CVSPACE 
+CVEXTS 
+CVBUFL2 
+CVVRFDA 
+CVCTAR 
+CVPLNGTH 
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PPPPrryppPppryprryprraTs 


*-CVPLMAP 


+X VALUES OF CVSTAT 
+X( THIS Penne? THE ICVAFPL MACRO EXPANSION IS NOT SHOWN) 


CVAFVRF ACCESS=WRITE 
STATUS INFORMATION CSEE LIST 


BELOW) 


FIRST FLAG BYTE 
INDEXED VTOC ACCESSED 
IOAREA=KEEP 
BRANCH=CYES,PGM) 
MAPRCDS=YES 
IXRCDS=KEEP 


MAP=INDEX 
MAP=VTOC 


MAP=VOLUME 
SECOND FLAG BYTE 
HIVIER=YES 

VRF DATA EXISTS 


COUNT=YES 


RECOVER=YES 
SEARCH=YES 
DSNONLY=YES 
VERIFY=YES 
OUTPUT-NEW HIGHEST LEVEL VIER 


CREATED 
RESERVED 


UCB ADDRESS 

DATA SET NAME ADDRESS 

BUFFER LIST ADDRESS 

INDEX VIR'S BUFFER LIST ADDRESS 
MAP VIR'S BUFFER LIST ADDRESS 
I70 AREA ADDRESS 

DEB ADDRESS 

ARGUMENT ADDRESS 

SPACE PARAMETER LIST ADDRESS 
EXTENT TABLE ADDRESS 

NEW VRF VIXM BUFFER LIST ADDR 
VRF DATA ADDRESS 

COUNT AREA ADDRESS 


3 





—_ 
Soe 

















EXAMPLE 5: USING THE CVAFTST AND CVAFDSM MACROS 


EXAMPLE5 CSECT 
OTM 


This example returns a format-5 DSCB to the caller. The 
format-5 DSCB is constructed by this program if the volume 
contains an indexed VTOC. The format-5 DSCB is read by another 
program, F5RTN Cnot described in the example), if the volume 
contains a nonindexed VTOC. 


The CVAFTST macro is used to determine if a nonindexed VTOC is 
on the volume. 


If the CVAFTST return code is neither 0 nor 4 Ca nonindexed VTOC 
is on the volume), the CVAFDSM macro is issued to obtain up to 
2/7 extents from the VPSM in the VTOC index. The program does 
not determine whether the CVAFTST return code is 8 Cvolume 
contains indexed VTOC) or 12 (it cannot be determined what type 
of VTOC is on the volume). In either case, the CVAFDSM macro is 
issued. If the CVAFTST return code is 12, the CVAFDSM macro 
call will cause CVAF to determine whether an indexed or a 
nonindexed VTOC is on the volume, and the CVLIVT bit will be set 
to one or zero, accordingly. 


The extent table Cat label EXTABL) is initialized to request 27 
extents from the CVAFDSM macro, which is one more than the 
number of extents that fit ina format-5 DSCB. The format—5 
DSCB is constructed from the first 26 extents returned from the 
CVAFDSM call. 


The first extent in the extent table is initialized from the 
last extent in the format-5 DSCB area supplied by the caller of 
the program. If this is the first call, the program assumes 
that the format-5 area is initialized to zero. Thus, the first 
extent in the extent table has a value of zero to serve as the 
starting place for the extent search. If this is the second or 
subsequent call, the last extent in the format-5 area would be 
the last extent obtained from the previous CVAFDSM call. 


The format-5 chain pointer field (DSS5SPTRDS) is set to a nonzero 
value if CVAFDSM returned a 27th extent. In this case, the 
program will be called again to obtain another format-5 DSCB. 


The program's return code is 0 if no errors were encountered and 
4G if an error was encountered. 


This program must be APF authorized. 


14,12,12€13) 

BALR 12,0 

USING X,12 

ST 13,SAVEAREA+4 

LA RWORK, SAVEAREA 

ST RWORK,8(,13) 

LR 13,RWORK 
HEHE HE HEHE HEHEHE HE HEHE HEHE DE HE HE HE HE HE HE HEHE HE HE HE HE HE HE IE HE HE IE HE HE HE HE HEHE HE HE HE HE DE IE DE DE NE HE HE HE IE HE HE HE IE HE HEHE IE IK 
x 
X REGISTERS 
% 
HH HE HEHE HEHE HEH HEHEHE HEHE HE HEHE HEHE HE HE HE HE HEHE HEHE HE HE HE HEHE HEHE HE HE HE HE HE HE HE HE HEHE HE HE HE HE HEHE HE HEHEHE HE HE HEHE EE 
RDEB EQU] 3 DEB ADDRESS SUPPLIED BY CALLER 
RUCB EQU 4 UCB ADDRESS SUPPLIED BY CALLER 
RF5 EQU) 5 ADDRESS OF FORMAT 5 BUFFER SUPPLIED x 

BY CALLER 

RWORK EQU 6 WORK REGISTER 
REGI5 EQU 15 RETURN CODE REGISTER 15 
X 
KF5 EQU 26 NUMBER OF FORMAT 5 EXTENTS 
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nat TERTRTT RT Ae we EE ET OE C ETE 














HEHE HE HE HE DE DE KE HE IE HE DE FE HE HE DE DE HE HE HE HE DE HE HEHE HE HE HE DE HE HE HE HE HE DEE HEHE HE DE DE HE HE HE HE HE HE HE HE JE JE HE HE HE HE DE TE HE DEE 


X 
% READ FORMAT 5 DSCB OR BUILD A FORMAT 5 DSCB IF 

% AN INDEXED VTOC 

x UCB ADDRESS SUPPLIED IN RUCB. 

% RF5 CONTAINS THE ADDRESS OF THE FORMAT 5 DSCB BUFFER. IT 

% CONTAINS THE LAST FORMAT 5 DSCB READ OR BUILT. THE FORMAT 5 
x 
x 
x 
x 
% 
% 





BUFFER IS ZERO IF THIS IS THE FIRST CALL 

IF THE FORMAT 5 DSCB BUFFER RETURNED TO THE CALLER HAS A 
NONZERO VALUE IN DSSPTRDS, THIS ROUTINE WILL BE CALLED 
AGAIN TO OBTAIN THE NEXT FORMAT 5 DSCB. 


HEHEHE HE HE HE HE DE HE HE DE DE HE HE HE HE HE HE HE DE IE HE HEHE DE HE HE DE DE HE HE HE IE HE DE HE HE HE DE HE HE HE HE HE HE IE HEHE HE HE IE HE HE HEHE HEHE EE | 
USING IECSDSF5,RF5 ADDRESSABILITY TO FORMAT 5 BUFFER 


CVAFTST UCB=CRUCB) TEST VTOC 
+ CNOP 0,4 START OF CVAFTST MACRO 
+ LR 1,RUCB LOAD PARAMETER REG 1 
+ L 15,16 LOAD THE CVT 
+ L 15,328(¢,15) LOAD VS1/VS2 COMMON EXTENSION2 
+ L 15,12¢€,15) LOAD THE CVAF TABLE ADDRESS 
+ LTR 15,15 TEST FOR ZERO VALUE 
+ BZ ICVI1E CVAF IS NOT ON THE SYSTEM 
+ L 15,4¢€,15) LOAD POINTER TO CVAF TEST E.P. 
+ BALR 14,15 BRANCH AND LINK TO CVAF TEST 
+ICVIE EQU % END OF CVAFTST 
LTR REG15,REG15 
BZ UNINDXD READ NEXT FORMAT 5 
C REG15,NOTIXRC UNINDEXED VTOC? 
BE UNINDXD ~ READ NEXT FORMAT 5 
HHH HEHE HEHEHE EE HE HEHE HE DE HE HE HE HE DE HEE FETE HE IE HE TE HE HE IE EE TEE HE HE DE HE HE HE HE DE HE DE HEHE HE DE HE HE HE DE HE HEE HH HEN 
¥ 
% ASSUME INDEXED VTOC UNLESS CVAFDSM CALL INDICATES UNINDEXED 
x 


HEH HEHE HK HEHE HEH HE HEHE HEHE HE EH HE EHEC HE HEHE HEHE HEHE HE EE HE HE DE DE HE HE DE HE DE HE HEHE DE HEHE DE DE HE DE EE DE HE DEE HE HE HEE 


MVC 8 =EXTSCL'DSSAVEXT), DSSMAVET+L* DSSMAVET-L*DSSAVEXT MOVE THE xX 
LAST EXTENT FROM FORMAT 5 TO FIRST xX » 
ENTRY IN THE EXTENT TABLE fo ™ 
CVAFDSM ie CE,CVPL), GET 27 EXTENTS FROM CVPL % Ke 
UCB=(RUCB), RUCB ADDRESS REQUIRED ¥ “ 
DEB=CRDEB), RDEB ADDRESS REQUIRED BY ¥ 
UNAUTHORIZED PROGRAMS CALLING CVAF xX 
: BRANCH=YES BRANCH ENTRY CALL % 
+ LA 1,CVPL LOAD PARAMETER REG 1 
+ L 15,16 LOAD THE CVT 
+ L 15,328¢,15) LOAD VS1/VS2 COMMON EXTENSION2 
+ L 15,12¢€,15) LOAD THE CVAF TABLE ADDRESS 
+ L 15,0¢,15) LOAD THE CVAF ADDRESS 
+ BALR 14,15 BRANCH AND LINK TO CVAF 
™ CVFL1,CVIIVT IS THIS INDEXED YVTOC 
BZ UNINDXD READ FORMAT 5 IF NOT 
LTR REG15,REG15 ANY ERROR 
BZ NOERROR 
C REG15,RCO4 
BNE OQTHERERR UNEXPECTED ERROR 
CLI CVSTAT,STATO32 END OF DATA 
BNE OTHERERR UNEXPECTED ERROR 
NOERROR EQU x BUILD FORMAT 5 
MVC DSSKEYID,F5ID 
MVC DS5AVEXTCL* DS5SAVEXT+L * DS5SEXTAV),EXTS MOVE IN EXTENTS * 
TO DSSFMTID 
MVI DSSFMTID,C'5!® 
MVC PROM Nn eee nedt ree eee nak MOVE REMAINING % 
XR REG15,REG15 RETURN CODE ZERO 
XC DSSPTRDS,DSSPTRDS ZERO CHAIN POINTER 
NC EXTS#L 'EXTS-L* DSSAVEXTCL * DSSAVEXT), EXTS+L "EXTS-L ' DSSAVEXTX 
een EXTENT FROM CVAF % 
? 
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BZ RETURN BRANCH IF YES-LEAVE DS5PTRDS ZERO 
MVI DSSPTRDS+L*DSSPTRDS-1,1 SET DSSPTRDS NONZERO TO SIMULATE xX 
THERE BEING ANOTHER FORMAT 5 


B RETURN 
UNINDXD EQU xX CALL ROUTINE TO READ NEXT FORMAT 5 
LINK EP=F5RTN LINK TO FORMAT 5 ROUTINE. RETURN % 
CODE PASSED BACK IN REGI5 
+ CNOP 0,4 
+ BAL 15,*+20 LOAD SUP.PARAMLIST ADR 
+ DC ACK+8 ) ADDR OF EP PARAMETER 
+ DC ACO) DCB ADDRESS PARAMETER LCOA 
+ DC CL8'F5RTN* EP PARAMETER 
+ SVC 6 ISSUE LINK SVC 
RETURN EQU xX RETURN TO CALLER 
L 13,SAVEAREAt+4 
RETURN (€14,12),RC=(15) 
+ L 14,12013,0) RESTORE REGISTER 14 
¥ LM 0,12,20€13) RESTORE THE REGISTERS 
+ BR 14 RETURN 
OTHERERR EQU % ERROR 
L REG15,RC04 ERROR RETURN CODE 
B RETURN 
DSCB DSECT 


IECSDSL1 (5) 
*#IECSDSL5 EQU * 
+IECSDSF5 EQU ITECSDSL5 


FORMAT 5 DSCB 


+DS5KEYID DS XL4 KEY IDENTIFIER 

+DS5SAVEXT DS XL5 AVAILABLE EXTENT 

+X BYTES 1 - 2 RELATIVE TRACK ADDRESS OF THE FIRST TRACK 
+X IN THE EXTENT 

+X BYTES 3 - 4 NUMBER OF UNUSED CYLINDERS IN THE EXTENT 
+X : BYTE 5 NUMBER OF ADDITIONAL UNUSED TRACKS 
+DSSEXTAV DS XL35 SEVEN AVAILABLE EXTENTS 
+DSSFMTID DS CLI FORMAT IDENTIFIER 

+DSSMAVET DS XL90 EIGHTEEN AVAILABLE EXTENTS 
+DSSPTRDS DS XL5 POINTER TO NEXT FORMAT 5 DSCB 


+DS5END EQU % 
EXAMPLE5 CSECT 


NOTIXRC DC FYGgt CVAFTST RETURN CODE-UNINDEXED 
RCO4 DC FG? RETURN CODE 4 
F5ID DC XL4*0505050505'* FORMAT 5 FIELD, DSSKEYID 
SAVEAREA DS 18F REGISTER SAVE AREA 
EXTABL DS OCLC 1+CKF5t+1)*L*DSSAVEXT) EXTENT TABLE 
EXTNO DC ALICKF54+1) NUMBER OF EXTENTS IN TABLE 
EXTS DS CLO CKF54+1)*L*DSSAVEXT) EXTENTS 
CVPL CVAFDSM ACCESS=MAPDATA, X 
COUNT=NO, DO NOT COUNT EXTENTS ¥% 
MAP=VOLUME, ACCESS VOLUME SPACE MAP * 
EXTENTS=EXTABL, EXTENT TABLE ADDRESS ¥% 
MF=L LIST FORM OF MACRO 
+ CNOP 0,4 
+CVPL EQU *% 
+ DC CL4*CVPL'* EBCDIC *CVPL* 
+ DC AL2CICV9E-CVPL) LENGTH OF CVPL 
+ DC XL1'OA* FUNCTION CODE 
+ DC XL1‘'00! STATUS INFORMATION 
+ DC BYOO1LOOOOL* FIRST FLAG BYTE 
+ DC B*00000000° SECOND FLAG BYTE 
+ DC H*Q? RESERVED 
+ DC ACO) UCB ADDRESS 
+ DC AC0) DATA SET NAME ADDRESS 
+ DC AC0) BUFFER LIST ADDRESS 
+ Dc AC0) INDEX VIR'S BUFFER LIST ADDRESS 
+ DC AC0) MAP VIR'S BUFFER LIST ADDRESS 
+: DC AC0) I70 AREA ADDRESS 
+ pc AC0) DEB ADDRESS 


Appendix B. Examples of VTOC Access Macros 219 




















DC ACO) ARGUMENT ADDRESS 





+ 
+ DC ACO) SPACE PARAMETER LIST ADDRESS 
+ DC ACEXTABL) EXTENTS TABLE ADDRESS 
+ DC ACO) NEW VRF VIXM BUFFER LIST ADDR 
+ DC AC0) VRF DATA ADDRESS 
+ DC ACO) COUNT AREA ADDRESS 
+ICV9E EQU] x END OF CVPL 
ORG CVPL OVERLAY CVPL WITH EXPANSION OF MAP 


CVPLMAP ICVAFPL DSECT=NO 
+ HHH HH HHH IEH HEH HEHE HEHE HEHE YE HE HEHEHE HEHEHE HEHEHE HEI HEIDEN HEHE IE HEHE HEH HEH HEH HEHEHE HE IE HEH HEHE HEHE HE HE HE HEH HEN HEH IE 


+X CVAF PARAMETER LIST 

HE HEHE HEHE HEHEHE HE HE HE HEE HEHE DE HE HE HE HE HEHE DEE HEHE HEHEHE HE HE DE DE HEHEHE DE HE HE DE HEE DE HE HE HE DE DE DE DE DE DE DE DE DE HE DE DE DE DE DE DE DE DE DE DEDEDE EEE 
+CVPLMAP DS OF CVAF PARAMETER LIST 

+CVLBL DS CL4 EBCDIC 'CVPL' 

+CVLTH DS H LENGTH OF CVPL 

+CVFCTN DS XL1 FUNCTION BYTE 

+CVDIRD EQU XFO1l* CVAFDIR ACCESS=READ 

+CVDIWR EQU X'02' CVAFDIR ACCESS=WRITE 

+CVDIRLS EQU X'03' CVAFDIR ACCESS=RLSE 

+CVSEQGT EQU X'0¢' CVAFSEQ ACCESS=GT 

+CVSEQGTE EQU X'05! CVAFSEQ ACCESS=GTEQ 

+CVDMIXA EQU X'06' CVAFDSM ACCESS=IXADD 

+CVDMIXD EQU X'07' CVAFDSM ACCESS=IXDLT 

+CVDMALC EQU X*08!' CVAFDSM ACCESS=ALLOC 

+CVDMRLS EQU X*O9! CVAFDSM ACCESS=RLSE 

+CVDMMAP EQU X'OA' CVAFDSM ACCESS=MAPDATA 

+CVVOL EQU X*OB! CVAFVOL ACCESS=VIBBLD 

+CVVRFRD EQU X'OC! CVAFVRF ACCESS=READ 

+CVVRFWR EQU X'OD* CVAFVRF ACCESS=WRITE 

+CVSTAT DS XL1 STATUS INFORMATION CSEE LIST X 
+ BELOW) 

+CVFLI DS XL1 FIRST FLAG BYTE 

+CVIIVT EQU X'80! INDEXED VTOC ACCESSED 

+CVIIOAR EQU X'GO' TOAREA=KEEP 

+CV1PGM EQU X'20! BRANCH=CYES, PGM) 

+CVIMRCDS EQU X'10! MAPRCDS=YES sz 
+CVIIRCDS EQU X'08! IXRCDS=KEEP _—. 
+CVIMAPIX EQU X'04' MAP=INDEX ol 
+CVIMAPVT EQU X'02' MAP=VTOC ee 
+CVIMAPVL EQU X*O1'* MAP=VOLUME 

+CVFL2 DS XL1 SECOND FLAG BYTE 

+CV2HIVIE EQU X'80! HIVIER=YES 

+CV2VRF EQU X*40! VRF DATA EXISTS 

+CV2CNT EQU X*'20!' COUNT=YES 

+CVZRCVR EQU X'10! RECOVER=YES 

+CV2SRCH EQU X'08! SEARCH=YES 

+CV2DSNLY EQU X'04! | DSNONLY=YES 

+CV2VER EQU X*02' VERIFY=YES 

+CV2NLEVL EQU X*01' OUTPUT-NEW HIGHEST LEVEL VIER 

+X : CREATED 

+ DS H RESERVED 

+CVUCB DS A UCB ADDRESS 

+CVDSN DS A DATA SET NAME ADDRESS 

+CVBUFL DS A BUFFER LIST ADDRESS 

+CVIRCDS DS A INDEX VIR'S BUFFER LIST ADDRESS 
+CVMRCDS DS A MAP VIR'S BUFFER LIST ADDRESS 
+CVIOAR DS A I70 AREA ADDRESS 

+CVDEB DS A DEB ADDRESS 

+CVARG DS A ARGUMENT ADDRESS 

+CVSPACE DS A SPACE PARAMETER LIST ADDRESS 
+CVEXTS DS A EXTENT TABLE ADDRESS 

+CVBUFL2 DS A NEW VRF VIXM BUFFER LIST ADDR 
+CVVRFDA DS A VRF DATA ADDRESS 


+CVCTAR DS A | COUNT AREA ADDRESS 
core EQU *-CVPLMAP 


VALUES OF CVSTAT 
PXCTHIS Paar THE ICVAFPL MACRO EXPANSION IS NOT SHOWN) 
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EXPLANATION 


SYSTEM ACTION 


PROGRAMMER RESPONSE 








When CVAF finds an error ina VTOC index, it issues this 
message: 


ITEC606I VTOC INDEX DISABLED ON dev,volser, 


code, [rbal,secno, offset] ] 





In addition, CVAF puts a return code in the CVSTAT field of the 


The Common VTOC Access Facility CCVAF) detected a VTOC index 
error on the device 'dev' with volume serial number 'volser'. 
"code" is a number that represents the kind of VTOC index error 
encountered. 'rba*® is the RBA of the VIR in the VTOC index that 
contains a structure error indicated by ‘code’. If the VIR is a 
VIER, the section number in the VIER containing the VTOC index 
entry 18S supplied in ‘'secno'’, and the offset into the section of 
that VTOC index entry is supplied in ‘offset". 


The VTOC index is disabled by zeroing the index bit in the 
format-4 DSCB and setting the bit in the first high-level VIER 
that indicates invalid VTOC index structure. The VTOC will be 
converted to nonindexed format when DADSM next allocates space 
on the volume. A system dump is written to the SYS1.DUMP data 
set, and an entry is made in the SYS1.LOGREC data set. The 
message LEC6041 Cwhich indicates that the VTOC convert routines 
have been used) will be issued later. 


Examine the system dump anda print of the VTOC index, and use 
the information in message IEC606I to determine the cause of the 
VTOC index structure error. 


ROUTING AND DESCRIPTOR CODES 





The routing codes are 4 (direct access pool) and 10 
rede a maintenance), and the descriptor code is 4 (system 
status). 


Appendix C. VTOC Index Error Message and Associated Codes 221 











4(04) 


5(05) 


— 6006) 


7007) 
8108) 


9(09) 


LOCOA) 
11(0B) 
12(0C} 
13(0D) 


L4(0E} 
L5(COF) 


17011) 


19(13) 


22(16) 


23(17) 


24(18) 





Meaning 


No error. 


Data set name not found, or 
VIER is empty. 


Argument is outside VTOC 
extents or RBA range of VTOC 
index. 


Invalid parameter supplied 
Cwrong key). 


DSN keyword omitted. 


Not authorized to perform this 
function. 


Buffer list omitted. 


DEB invalid or omitted or not 
open to VTOC 


IOAREA=KEEP and user not 
authorized, or I/0 area 
supplied and user not 
authorized 


Function not supported on OS 
VTOC. 


DSCB is not format-0 DSCB and 
VERIFY=YES. 


MAPRCDS=YES and/or IXRCDS=KEEP 
but VTOC is nonindexed. 


IXRCDS=KEEP not specified for 
CVAFDSM ACCESS=IXADD or IXDLT. 


CTAREA Keyword omitted. 


UCB invalid, volume not 
mounted; VIO unit, not DASD. 


DSCB length invalid for the 
function requested: 96 bytes 
for CVAFDIR 
ACCESS=WRITE,VERIFY=YES; 96 
bytes for CVAFSEQ reading in 
data-set-name sequence; 1490 
bytes for CVAFSEQ reading in 
physical sequence. 


UCB omitted and CVAF I/0 area 
not supplied. 7 


Data set name already 
supplied. 


Invalid DSN supplied (44 X'FF* 
is a reserved data set name). 


ARG keyword not supplied. 
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Code 
25(19) 


27(1B) 


28(1C) 


29(1D) 


SOC 1E) 


S1IC1F) 


32(20) 


33(21) 


34(22) 


42(2A) 
43 (2B) 


44(2C) 





Meaning 





Conflicting or incomplete —. ! 
information specified in the | 
space table for a CVAFDSM | 
ACCESS=ALLOC, MAP=VOLUME | 
request. 


VTOC index full. No free VIRs 
available and a VIER split is 
required. 


Space Keyword omitted CCVSPACE 
field zero in CVPL). 


CVAFDSM ACCESS=ALLOC: No 
format 0 DSCB available 
CMAP=VTOC), or VTOC index full 
C(MAP=INDEX), or volume space 
not available CMAP=VOLUME). 


CVAFDSM ACCESS=ALLOC: CCHHR 
CMAP=VTOC) or. RBA MAP=INDEX or 
volume space extent 
CMAP=VOLUME) already 
allocated. 


CVAFDSM ACCESS=ALLOC or 
ACCESS=MAPDATA: CCHHR 
supplied outside VTOC extents 
CMAP=VTOC), or RBA outside 
VTOC index extents 
CMAP=INDEX), or volume space 
extent invalid or outside _ 
volume (CMAP=VOLUME). Get 


End of data. CVAFDSM S_/ 
ACCESS=MAPDATA: no more free 
extents in VPSM. CVAFSEQ: no 
more names in index or DSCBs 
in VTOC. For indexed access; 
no DSN in VTOC index with 
higher or higher-or-equal key 
than that supplied. For 
physical-sequential access, no 
DSCB in the VTOC has a higher 
argument than that supplied. 
For a multiple DSCB request, 
the last DSCB in the VTOC was 
read and more DSCBs were 
requested. 


EXTENTS keyword omitted, or 
supplied number of extents is 
zero. 


CVAFDSM ACCESS=RLSE1 format 0 
DSCB already free (CMAP=VTOC), 
or VIER already unallocated 
CMAP=INDEX) or volume space 
extent already unallocated 
CMAP=VOLUME). 





YRF data supplied for write 
too long. 


Buffer list is for VIRs, but a 
DSCB buffer list is required. 





No buffer list entry found. 

















Code 
45(2D) 


46(2E) 


47(2F ) 


48(30) 


49(31) 


50(32) 


52(34) 


53(35)} 


54(36) 


55(37) 


56(38) 


57(39) 


58(3A) 


60(3C) 


127(7F } 


128(80) 


129(81) 


130(82) 


131(83) 








Meaning 


Invalid DSCB buffer length 
Cneither 96 nor 140) in buffer 
list entry, or VIR buffer 
length not equal to VIB VIR 
size. 


Neither TTR nor CCHHR bits set 
in buffer list entry to be 
used in writing or reading a 
140-byte DSCB. 


More than one of the TTR, 
CCHHR, and RBA bits set in the 
buffer list entry. 


Both the DSCB and VIR bits set 
in the buffer list header. 


RBA bit set in a buffer list 
entry for a DSCB buffer list. 


TTR or CCHHR bit set in buffer 
list entry but buffer list 
header indicates buffer list 
is for a VIR 


Combination of MAP and COUNT 
not supported. 


MAP omitted. 


Buffer list for a VIR chained 
lg from a buffer list for a 


Unauthorized caller and VIB 
not initialized. 


MAPRCDS=YES not specified but 
required. 


Buffer list for a DSCB 
supplied, but buffer list for 
a VIR is required (in MAPRCDS 
or IXRCDS buffer list address 
in CVAF parameter list). 


Neither the VIR nor DSCB bit 
set ina buffer list header. 


Invalid or conflicting setting 
of allocate option byte in 
space parameter 


I/O error occurred. 
Reserved. 


The first high-level VIER as 
indicated in the VIXM does not 
have the flag bit set 
indicating it is the first 
high-level VIER. 


A horizontal or vertical VIER 
pointer is outside the RBA 
range of the VTOC index. 


A vertical VIER pointer points 


to a VIR that is not a VIER 
Cinvalid ID in header). 
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Code 
132(84) 


133(85) 


134(86) 


135(87) 


136(88 ) 


137089) 


138(8A) 


139 (8B ) 


140(8C) 


141(8D) 


142(8E) 


L430 8F } 


144(90) 


VTOC Index Error Message and Associated Codes 








Meaning 


A level n vertical index entry 
pointer points to a VIER that 
is not at level n - 1 


Level n horizontal index entry 
pointer points to VIER that is 
not at level n. 


Horizontal VIER/map pointer 
points to a VIR that is not a 
VIER/map Cinvalid ID in 
header). 


Horizontal map pointer points 
to VIR that is not one of the 
first n VTOC index records (Cn 
is recorded in VIXM field 
VIMRCDS), or the first record 
aeoaee VTOC index is not a 


A level-1l index entry contains 
a CCHHR pointer that is 
outside the VTOC extent. 


The first high-level VIER, as 
indicated in the VIB, does not 
have the flag bit set 
indicating it is the first 
high-level VIER. (This error 
is either recovered from by 
updating the VIB from the 
VIXM, or the error is changed 
to 129.) 


The RBA of the VTOC index VIR 
does not match the RBA 
recorded in the header of the 
record. 


The first record of a map 
CVIXM, VPSM, or VMDS) is not 
one of the first n VTOC index 
records (n is recorded in the 
VIXM field, VIMRCDS). 


The data set name ina level n 
+ ] VIER entry is lower than 
the high key of the level n 
VIER that the level n + 1 VIER 
entry points to. 


First high-level VIER 
structure error bit is on. 


I/0 error indicating the VTOC 
index is not formatted 
correctly. 


Either the index bit is zero, 
or the DOS bit is zero in the 
format~-4 DSCB of a VTOC 
previously found to be an 
indexed VTOC. 


No SYSI1.VTOCIX.nnn data set 
name in a VTOC whose format~-4 
DSCB has the index bit on, 
indicating the VTOC has an 
index. 
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Code 
145(91) 


146(92) 


147093) 


148(94) 


149(95) 


150(96) 


151(97) 


152(98) 





Meaning 


The data set name ina level n 
+ 1 VIER entry is higher than 
the high key of the level n 
VIER that the level n + 1 VIER 
entry points to 


Four or more high-level VIERs 
were encountered. 


Too many levels in the VTOC 
index. The length of the 
search list was exceeded. 


VIER invalid, because offset 
to last section is invalid. 


VIER invalid, because offset 
to last entry ina section is 
invalid. 


Media Manager initialization 
failed. 


Level-2 or higher VIER 
contains fewer than two 
entries. 


RECOVER=YES specified, but the 
static text module CICVIXSTO) 
indicates recovery is not 
permitted. 
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Code 
153199) 


154(9A) 


155(9B } 


156(9C) 


157(9D) 


158(9E) 


159(9F } 


Meaning 


The format-4 DSCB on an 
indexed VTOC is written with 
either the index- or DOS-bit 
zeroed on an indexed VTOC. 





A space map extends over more 
than 10 VTOC index records. 


Data set name not found in 
section with Key greater than 
or equal to the name being 
searched for. The VIER 
section containing the name is 
invalid. | 


Invalid VIER horizontal | 
pointer. Horizontal pointer 
of VIER] points to VIER2 whose 
high key is lower than or 
equal to the high key of 
VIER. 7 


Could not find entry in 
level-2 or higher VIER that 
a eG ae the high Key of the 


Invalid section length or 
invalid number of sections in 


a VIER header. 


The first high-level VIER 
pointed to by the VIB has an 
invalid ID in the header. oN 























PROCESSING IN IFGOEXOB 


The following program listing 1s a sample of IFGOEX0B. The four 
subroutines (BUFNO, SCREEN, RLSE, and SQTY) show examples of the 
kind of processing that can be done in your installation's 
version of IFGOEXOB. 


The BUFNO subroutine defaults the number of buffers for QSAM 
DCBs CDCBBUFNO) if the value is zero when the exit is given 
control. The block size in the DCB CDCBBLKSI) is used, together 
with a fixed amount of storage (64K bytes in the example) to 
determine a buffer number. A buffer number is limited to a 
fixed value (32 in the example). Storage quantity and maximum 
buffer number are contained in two tables, DAMAX and TPMAX, that 
are used for DASD devices and tape devices, respectively. 
Storage quantity is expressed in units of 1024 (1K) bytes. The 
values in the DAMAX and TPMAX tables can be altered by your 
installation. 


The SCREEN subroutine determines those cases in which the 

succeeding subroutines, RLSE and SQTY, should be executed. DASD 

sequential and partitioned data sets being processed by BSAM or 
QSAM and opened for OUTPUT or OUTIN are selected. The VTOC data 

set and data sets starting with 'SYS]1.' (system data sets) are 
rooa alae An installation may want to make further selection 
ests. 


REQUESTING PARTIAL RELEASE 


The RLSE subroutine sets on the partial release indicators in 
the JFCB if the number of extents in the data set is less than a 
fixed value (8 in the example). It sets off the partial release 
indicators in the JFCB if the number of extents in the data set 
1s equal or greater than a fixed value (8 in the example). 
Partitioned data sets are not processed, because they may be 
opened many times to write one new member for each OPEN/CLOSE. 


UPDATING THE SECONDARY SPACE DATA 


The SQTY subroutine provides a default secondary space quantity 
if none is specified. The default is one half of the primary 
space quantity if it is greater than one. If the primary 
quantity 1s zero, secondary is set to a fixed default number of 
tracks €5 in the example). If the primary quantity is one, 
secondary is set to the same fixed default (5); note that, in 
this case, the secondary quantity is in units of tracks, 
cylinders, or average blocks, depending on the unit of the 
primary quantity. 


If the secondary space quantity is not zero, the SQTY subroutine 
tests the number of extents in the data set. If the number of 
extents 1s equal to or greater than a fixed value (10 in the 
example), then the secondary quantity is increased by 50% if it 
is greater than l. It is set to a default quantity (5 in the 
example) if the secondary quantity is one; note that, in this 
case, the secondary quantity is in units of tracks, cylinders, 
or average blocks, depending on that of the primary quantity. 
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IFGOEXOB CSECT 
HEI HEHEHE HEHEHE HEHEHE IE HEHEHE IE HEI HEB HEHEHE HEHE HEHE HEHE HED HEHE HEH HEHE HEI HEB HEH HEH HEI HEI HE YE HEHEHE YEH IE HEHEHE YEH HEH HEH HEHEHE 


KK OK OK OK OK OK OK OK OOK OK OK OK OK OK OK OOK OK OOK OOK OK OK OOK OK OK OK OOK OK OOK OOK OOK OOK OK OK OK OK OK OK OOK OK OK OK OK OK OK OOK OOK OK OK OOK OOK OOK OK OK OK OOK OK OK OK OK OK MK OK 


FUNCTION = 


FOUR SAMPLE ROUTINES ARE SUPPLIED. 


BUFNO - DEFAULT DCBBUFNO 


DCBBUFNO (NUMBER OF BUFFERS) IS DEFAULTED FOR 

OPENS TO PHYSICAL SEQUENTIAL AND PARTITIONED DATA SETS | 
ON DASD AND TAPE USING QSAM, FOR WHICH DCBBUFNO IS ZERO. 
DCBBUFNO FOR SYSIN, SYSOUT, TERMINAL, AND DUMMY DATA SETS 
IS SET TO THE EQUATE, INOUTBNO, OR THE VALUE IN THE — 
FULLWORD, INOUTBN. 


DCBBUFNO IS SET TO THE NUMBER OF DCBBLKSZ BUFFERS WHICH 
FIT IN A GIVEN AMOUNT OF STORAGE. THE AMOUNT OF STORAGE IS 
DEFINED BY THE EQUATES, DAMXK AND TPMXK COR THE FULLWORDS 
AT LABELS, DAMAXK AND TPMAXK), FOR DASD AND 

TAPE, RESPECTIVELY. THE EQUATES DEFINE THE AMOUNT OF 
STORAGE FOR BUFFERS IN UNITS OF 1024 CIF DAMXK IS 32, THEN 
THE AMOUNT OF STORAGE IS 32K, OR 32768). 

DAMXK OR TPMXK TIMES 1024 IS DIVIDED BY DCBBLKSI TO 
DETERMINE THE NUMBER OF BUFFERS TO DEFAULT. 


THE EQUATES, DAMXBNO AND TPMXBNO, OR THE FULLWORDS 

AT LABELS, DAMAXBNO AND TPMAXBNO, 

DEFINE THE MAXIMUM NUMBER OF BUFFERS TO BE 

DEFAULTED FOR DASD AND TAPE IF THE CALCULATION, ABOVE, 
RESULTS IN A LARGER NUMBER. 


SCREEN - SCREEN OUT CASES FOR RLSE, SQTY 
RLSE - SET OR ZERO PARTIAL RELEASE 


THIS ROUTINE SETS PARTIAL RELEASE FOR DASD PS CNOT PO) DATA 
SETS BEING OPENED FOR OUTPUT OR OUTIN. 


PARTIAL RELEASE IS SET ON IF THE NUMBER OF EXTENTS IS LESS 
eee DEFINED BY THE EQUATE, RLSE1, OR THE BYTE, 


PARTIAL SR GUR IS SET OFF IF THE NUMBER OF EXTENTS IS NOT 
LESS THAN A QUANTITY DEFINED BY THE EQUATE, RLSEO, OR THE 
BYTE, EXTRLSEO. 


SQTY - SET OR UPDATE SECONDARY SPACE QUANTITY 


THIS ROUTINE UPDATES THE SECONDARY SPACE 
QUANTITY FOR DASD PS OR PO DATA SETS BEING 
OPENED FOR OUTPUT OR OUTIN. 


IF THE SECONDARY QUANTITY IS NOT ZERO, 
AND IF THE NUMBER OF EXTENTS IN THE DATA SET [5S 
AT LEAST EQUAL TO THE QUANTITY IN THE EQUATE, EXTSQT COR 
THE BYTE AT LABEL, EXTSQTY), THEN: 
1. IF THE SECONDARY QUANTITY IS GREATER THAN ONE, 
rea Need QUANTITY IS INCREASED BY ONE HALF 
“Ad. 
2. IF THE SECONDARY QUANTITY IS ONE, 
SECONDARY QUANTITY IS SET TO THE VALUE IN THE FULLWORD 
AT LABEL, SQTYDFLT CEQUAL TO THE EQUATE, SQTYDFL). 


IF THE SECONDARY QUANTITY IS NOT ZERO, 

AND IF THE NUMBER OF EXTENTS IN THE DATA SET IS 

LESS THAN THE QUANTITY IN THE EQUATE, EXTSQT COR 
THE BYTE AT LABEL, EXTSQTY), SECONDARY QUANTITY 

IS LEFT UNCHANGED. 
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IF SECONDARY QUANTITY IS ZERO, IT IS SET TO ONE HALF 

OF PRIMARY QUANTITY IF PRIMARY IS NOT ZERO OR ONE. 

IF PRIMARY QUANTITY IS ZERO, THE SPACE TYPE IS SET TO TRACKS, 
AND SECONDARY QUANTITY IS SET TO THE VALUE IN THE FULLWORD 
AT LABEL SQTYDFLT CEQUAL TO THE EQUATE, SQTYDFL). 

IF PRIMARY QUANTITY IS ONE, SECONDARY QUANTITY IS SET TO 
VALUE IN THE FULLWORD AT LABEL SQTYDFLT CEQUAL TO THE 

EQUATE, SQTYDFL). 


NOTES = SEE BELOW 


DEPENDENCIES = 
CLASS ONE CHARACTER CODE. THE EBCDIC CHARACTER CODE 
WAS USED FOR ASSEMBLY. THE MODULE MUST BE REASSEMBLED 
IF A DIFFERENT CHARACTER SET IS USED FOR EXECUTION. 


RESTRICTIONS = NONE 


REGISTER CONVENTIONS = 
Rl OIEXL ADDRESS 
R2 DCB ADDRESS 
R3 UCB ADDRESS 
R4 DCB BLOCK SIZE 
R5 ADDRESS OF TPMAX OR DAMAX TABLES 
R6 EVEN REGISTER OF EVEN/ODD PAIR 
R7 ODD REGISTER OF EVEN/ODD PAIR 
R&8 TIOT ENTRY ADDRESS 
R8 JFCB ADDRESS 
R10 FORMAT 1 DSCB ADDRESS 
Rll SAVE RETURN CODE 
SAVE AREA ADDRESS 
R14 RETURN ADDRESS 
R15 BASE REGISTER. 


PATCH LABEL = PATCH 
MODULE TYPE = CONTROL COPEN, CLOSE, EOV DATA MANAGEMENT > 
PROCESSOR = ASSEMBLER XF 
MODULE SIZE = SEE EXTERNAL SYMBOL DICTIONARY 
ATTRIBUTES = REENTRANT, REFRESHABLE,READ-ONLY, ENABLED, 
PRIVILEGED, SUPERVISOR STATE, KEY ZERO, 
LINK PACK AREA RESIDENT/PAGEABLE 
ENTRY POINT = IFGOEXOB 
PURPOSE = SEE FUNCTION 
LINKAGE = 
FROM IFGO196L: 
BALR 14,15 
INPUT = STANDARD LINKAGE CONVENTIONS 
OUTPUT = DCBBUFNO DEFAULTED 
PARTIAL RELEASE SET OR RESET 
CONTIGUOUS FLAG SET TO ZERO 
SECONDARY SPACE REQUEST MODIFIED 
RETURN CODE IN REGISTER 15 


0 IF JFCB NOT MODIFIED 
4 IF JFCB MODIFIED 
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RSS mic oi a al eS i hich shiping reheat cinerea teenage th il sn at 








en ee ae 
EXIT-ERROR = 
NONE 
EXTERNAL REFERENCES = SEE BELOW 
ROUTINES = NONE 
DATA AREAS = NONE 
CONTROL BLOCK = NONE 
TABLES = NONE 


MACROS = MODESET, ITECOIEXL, DCBD, IEFUCBOB, IEFTIOT1, IEFJFCBN, 
IECSDSLI 


HEE HE DE IE DE HE HE HE IE DE HE HE HE DE DE HE IE DE HE DE DE DE DE DE DE DE DE DE DE DE DE IE DE DE DE IE DE DE DE DE IE DE DE DE DE IE DE HE HE DE DE DE DE HE HE DE DE DE DE DE DE DEE HE DE HE DE HE HEE 
HEHE HE HE HEHE HE HE HEHE DE HE HE HE HE HE HEHE HE HE HE HE HE HE HE HEH HH HE HE HEHE HE HE DE HE HE HE HE HEHE HE_ DE TE HEHE HE HE HEH HE HE HE DEE HE HE HE EH HK HHH RAK HK HK HK 
X 


WK KOK OK KK OK OK OK OK OK OK OK OK OK OK OK OK OK OK 


% REGISTER EQUATES 

x 

HE HE HE DE DE FE DE DE HE DE HE HE DE DE DE DE DE IE DE DE DE DE DE DE DE DE DE IE DE DE DE HE IE IE HE DE HE DE IE IE DE DE DE HE DE IE IE DE DE HE TE DE DE DE HE IE HE HE DE DE HE HE DE DE HE IE HE DE HE HE HK 

Rl EQU 1 OIEXL PARAMETER LIST ADDRESS 

RDCB EQU 2 DCB ADDRESS 

RUCB EQU 3 UCB ADDRESS 

RBKSIZ EQU 4 DCB BLOCK SIZE 

RMAX EQU 5 ADDRESS OF TPMAX OR DAMAX 

REVEN EQU 6 EVEN REGISTER OF EVEN/ODD PAIR 

RODD EQU 7 ODD REGISTER OF EVEN/ODD PAIR. HAS 
DCBBUFNO DEFAULT 

RTIOT EQU 8 TIOT ENTRY ADDRESS 

RJFCB EQU 9 JFCB ADDRESS 

RDSCB EQU 10 FORMAT 1 DSCB ADDRESS 

RINCODE EQU ll INTERNAL RETURN CODE 

R12 EQU 12 

RSAVE EQU 13 SAVE AREA ADDRESS 

RET EQU 14 RETURN ADDRESS 


RCODE EQU. 15 BASE REGISTER/RETURN CODE ON EXIT 
HEHE HE HE DE HE HE HE HE HE HE HE HE HE HE HE HE HE HE HE HE HE HE IE HE HE HE HE HE DE HE DE HE HE HE HC HE HE HE HE HE IE HE HE HE HE HE HE HE HE IE HE DE HE HEHE HE HE HE HE DE HE HE HE IE DK HE HEHEHE 
x 


% RETURN CODE 

x : 

HE HE HE HE HE HE HE HE HE HE DE HE HE HE HE HE DE HE HE HE HE HE HE HE HE HE HEHE DE HE HE HEE DE HE HE HE DE DE DE HE DE HE HE HE HE HE HE HE HE HE DEE DE HE HE HE IE HEE HE DE DE HEHE EE EEK 
MODJFCB EQU = 4 RETURN CODE IF JFCB MODIFIED 


USING IFGOEX0B,RCODE 
3H HEHE IERIE HEI EHH DEED DEH IIE EDDE HED IEEE DERE DEH IEEE H DEIN DEH BE DEE DEDEDE EIDE 
x 


% START OF SAMPLE PROGRAM 

% 

DDE IED HEHEHE HEHEHE HEHE HEHE HEHE HEHEHE HEHE DEDEDE HEHEHE HEHE HEHEHE HEHEHE HHH HEH HH HEH HEHEHE IH HI 
B AFTRID1 


DC C'IFGOEXO0B JDM1137 &SYSDATE' 


+ DC C*IFGOEX0B JDM1137 05701781! 
AFTRID1 SAVE (14,12) SAVE REGISTERS 
+AFTRID1 DS OH 
+ STM 14,12,12(13) SAVE REGISTERS 
XR RINCODE,RINCODE ZERO RETURN CODE 
USING OIEXL,R1 PARAMETER LIST 
BAL RET, BUFNO — DEFAULT BUFNO 
BAL RET, SCREEN SCREEN OUT CASES WHERE RLSE, * 
AND SQTY SHOULD NOT BE CALLED 
BAL RET,RLSE SET PARTIAL RELEASE 
BAL RET,SQTY SET SECONDARY QUANTITY 
EXIT EQU % RETURN TO CALLER 
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% 





























DE DE DE DE DE DE DE DE HE DE DE DE DE DE DE DE DE DE DE DE DE DE DE 3E DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE JE DE DE DE DE DE DE DE DE 2E DE DE IE DE IE DE DE DE DE IE IE DE DE DE IE DE DE DE 3E HE JE IE 


x RETURN TO CALLER 
eo .. HE HEHE HEHE HE HE HE HE HE HE HE HE HE DE HE HE HE HE DE IE DE HE HE HE IE DE DE HE DE DE DE HE HE DE HE DE DE HE HE DE DE DE DE IE DE HE IE DE DE DE DE 3E DE DE DE DE DE DE DE DE DE DE DEE DE 9E 3 HE IE DE 
( | LR RCODE,RINCODE 
pena €14,12)3,RC=€15) RESTORE REGISTER 


+++ 


14,12€13 
CM ee ,20013) 


BR 


,0) 


RESTORE REGISTER 14 
RESTORE THE REGISTERS 
RETURN 


BUFNO EQU] xX DEFAULT DCB BUFNO 
HEHE HE HE HE HE HE HE HE DE HE DE HE HE DE DE HE DE HE DE HE DE HE DE DE IE DE IE HE HE DE HE DE HE HE HE HC DE IE DE HE HE IE DE DE DE IE HE HE HE DE DE DE DE IE IE DE HE DE IE DE IE IE DEE HE HE DE DE IE HE 


DEFINE DEFAULT VALUES 
DAMXK NUMBER OF K (1024) OF BUFFERS FOR DASD 


TPMXK = NUMBER OF K (1024) OF BUFFERS FOR TAPE 
DAMXBNO = MAXIMUM NUMBER OF BUFFERS FOR DASD 
TPMXBNO = MAXIMUM NUMBER OF BUFFERS FOR TAPE 


NOTE THAT DAMXBNO AND TPMXBNO MUST NOT BE GREATER THAN 255 


HEH HE HE HE HEHEHE HE HE HE HEHE HEHE HEHE HE HE HE HE HE HE HE HE HE HE HE HE DE HE HE HE HE HE DE HE IE HE DE HE HE HE HE HE HE HE IE HE HE HE DE HE HE IE 3E DE DE IE DE HE DE DE DE HE DE HE DE 3E 3E HE 

DAMXK EQU 64K BUFFERS FOR DASD 

TPMXK EQU 64 64K BUFFERS FOR TAPE 

DAMXBNO EQU 32 32 BUFFERS MAXIMUM FOR DASD 

TPMXBNO EQU 32 32 BUFFERS MAXIMUM FOR TAPE 

INOUTBNO EQU- 1 DCBBUFNO DEFAULT FOR SYSIN, SYSOUT, xX 
AND DD DUMMY 


KK OK OK OK OK OK OK 


ONEK EQU 10 SHIFT ARGUMENT TO MULTIPLY BY 1024 
B AFTRID2 
DC CL&8"*BUFNO! BUFNO ROUTINE ID 


AFTRID2 BCR 0,RET NOP RETURN 
L RDCB, OTEXPDCB PROTECTED COPY OF DCB 
| USING DCBD,RDCB 


HEHE HE HEE HE IE IE HEHE DE DE DE DE HE HE DE DE DE HE DE DE DE HE HE DE HE HE HE DE DE HE HE HE DE DE HE HE HE HE HE HEE HE HE DE DE DE HEHE DE DE DE DE HE DE HE DE DE DE IE DE DE HE DE HE HEHE HE HEH 


X DO NOT PROCESS EXCP, BSAM, DSORG NOT PS OR PO, 
bs DCBBUFNO SPECIFIED 
HEH HE HEHE HEHE HE HEHE HE HE HE HEHE HE HE HEHE HEHE HE HEHE CHE HE HE HE HC HEHE IE HEHE HE HC HEHE HEHE HE HEHE HE HE HE HE HE HE HE HEHE HE HEHE CHE IE HEHE HE IE HE HE HEHEHE HEHEHE 
2 DCBMACF1,DCBMRECP EXCP DCB? 
. | BO RETBUFNO RETURN IF EXCP 
—— TM DCBMACF1,DCBMRRD READ MACRO 
- BO RETBUFNO RETURN IF READ-NOT QSAM 


WRITE MACRO 
RETURN IF WRITE-NOT QSAM 


™ DCBMACF2, DCBMRWRT 
BO RETBUFNO 


TM SERBRCHGG eee ae PS OR PO 


BZ RETBUFNO XIT IF NOT PS OR PO 
CLI DCBBUFNO, 0 IS DCBBUFNO SPECIFIED 
BNE RETBUFNO RETURN IF DCBBUFNO SPECIFIED 


HEHEHE HEHE HEHE HE HEHE HEHE HEHE HE HE HEH HEH HE HEHE HE HEH HEHE HE HEHE IE HEHE HE HEH HE HEHEHE HEHE HEHEHE HEHEHE HE HEHEHE HHH HEH HHH HHH HE HK HK HK 
bs DEFAULT DCBBUFNO TO 1 FOR SYSIN, SYSOUT, TERMINAL, DUMMY 
HEHE HE HEHE HEHE HEHE HE HC HE HE HEHE HEHE HEHE HE HEHE HE HE HE HEHE HE IE HE DE HE HE HE HE HEHE HE HE DE HE HE DE HE HE HE HE HE HE HE HE HE HE HE HEHE HEHE HE HEHE HK HE HE HEHE HEHE HEHE 
L RTIOT,OLEXTIOT TIOT ENTRY ADDRESS 
USING TIOENTRY,RTIOT 
L RODD, INOUTBN So NueM FOR SYSIN/SYSOUT/ % 
TM TIOELINK, TIOESSDS+TIOTTERM SYSIN/SYSOUT OR TERMINAL 
BNZ STORE BRANCH IF SYSIN OR SYSOUT OR TERMINAL 
L RJFCB,OITEXJFCB JFCB ADDRESS 
USING INFMJFCB,RJFCB 
CLC JFCBDSNMCL*NULLFILE),NULLFILE DUMMY DATA SET 
BE STORE BRANCH IF DUMMY 
HEHE HEHE HE HE HE HE IE HE HE HE HE HEHE HE HE HE IE HE HEHE HEHE HE HEH HEHE HE HEHE HE HE HE HEHE HEHE HE HEHE HEH HEHE HE HEHE HE HE HE HE HE HE IE HE HE HE IE HE HEHE HE HE HE IE IE HE EK 
x EXIT IF NO UCB ADDRESS OR BLOCK SIZE NOT POSITIVE 
HEHE HE HEHE HE IE HE HEHE HE HE DE HEHE HEH H HE HE HEHE HEHE NE HEHE HEHE HE HE HE HE HEHE HEHE HEHEHE HEH HEHE HEH HE HE HEHEHE HE HEHE HEHE HE HE IE HEHE HEHE HE HE HE HEHEHE HEE 
L RUCB, OLEXUCB UCB ADDRESS 
LTR RUCB,RUCB ANY UCB? 
BZ RETBUFNO EXIT IF NO UCB 
LH RBKSIZ, DCBBLKSI DCB BLOCK SIZE 
LTR RBKSTIZ,RBKSIZ ANY BLOCK SIZE? | 
BNP RETBUFNO RETURN IF NO BLOCK SIZE 


= ye TRAP TR EHR ann 4 He a 


TET RT URN TN eT 
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+ 
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+ 
+ 
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2 





HEHE HEHE HEHEHE HEHEHE HEHEHE IE HE HE HE HEHEHE I HE HEHEHE HEHE HE YE HE HE IE HE HE HE HE HE HEHE HEHE HE IE HE HE HE HE IE HE IE IE HE IE IE HE IE IE HE IE HEHE IE HE HE IE HE IE HE IE TEI 
% GET TAPE OR DASD MAX TABLE 
HHH HHH HHI HAA AAAI IASI DEIN III IIE DEE 
USING UCBOB, RUCB 
TM UCBITBYTS, UCB3DACC DASD UCB? 


LA RMAX, DAMAX MAX TABLE FOR DASD 

BO CALC BRANCH IF DASD 

™ UCBTBYT3,UCB3TAPE TAPE UCB? 

LA RMAX, TPMAX MAX TABLE FOR TAPE 

BZ RETBUFNO RETURN IF NOT DASD OR TAPE 
CALC EQU x DEFAULT DCBBUFNO 


HE HEHEHE HEHE HEHEHE HE HE HEHEHE HEHE HE HEHEHE HE DE HE HEHEHE DE HE HEH HE DE HE HE DE HE HEHE DE DE HE HE HE HEHE DE HEHE HE HE HE DE HE HE HE HE HE HE HEHE HE HE IEE HE HEE HE HEHEHE 


% CALCULATE DEFAULT BUFFER NUMBER 

HE HE HE HE HE HE HEHE HEHE HE IE HE HE HE DE HE HE HE HE IE HIE HEHE HE HE HE HEHE HEHE HE HE HE HE IE HEHE HE HE HE DE IE IE HE HE DE HE HE DE HE HE HE HE HE HE HE HE HE IE HE HE HE HE IE HE HE HE IE HE 
USING MAX, RMAX | 
XR REVEN, REVEN ZERO EVEN REG 


L. RODD, MAXBUF MAXIMUM STORAGE FOR BUFFERS 

SLL RODD, ONEK SHIFT TO MULTIPLY BY 1024 

DR REVEN, RBKSIZ DIVIDE MAS BUFFER SPACE BY BKSI 

C RODD, MAXBNO ARE THERE TOO MANY BUFFERS? 

BNH STORE USE CALCULATION IF NOT TOO LARGE 

L RODD,MAXBNO USE MAXIMUM NUMBER OF BUFFERS 
STORE EQU ¥ DEFAULT DCBBUFNO FOR USER/COPY DCB 

STC RODD, DCBBUFNO PUT IN PROTECTED COPY OF DCB . 

L RDCB, OITEXUDCB USER DCB 

XR REVEN,REVEN MODESET USES REG 6 = REVEN 

MODESET KEYADDR=OLTEXUKEY,WORKREG=6 GET IN USER KEY 
* /¥ MACDATE Y-3 77277 0ZA26071/ 
xX SK 

IC 6 , OTEXUKEY GET KEY FROM SAVE LOCATION 

SPKA 06) SET PSW KEY 

STC RODD, DCBBUFNO PUT IN USER DCB 

MODESET EXTKEY=ZERO BACK TO KEY ZERO 
* /¥® MACDATE Y-3 77277 0ZA26071%/ 
x 7% 

SPKA 0(€0) SET PSW KEY 
RETBUFNO EQU X RETURN FROM BUFNO 

RETURN 


BR RET | 
INOUTBN DC ACINOUTBNO) SYSIN/SYSOUT/DUMMY BUFNO DEFAULT 
HE HE HE HE HE DE IE HE IE HE HE IE HE HE HE HE HE HE HE HE HE HE HE HE IE DE IE DEE HE HE IE HE IE HE HE HC HE HE DE HE DE HE HE HE HE NE HE IE HE HE IE HE HE HE HE HE DE IE HE IE HE DE IE HE IE HE HE HEHE 
b 


x MAX TABLE FOR TAPE 

x 

HE HEH HE HEHE HE HE HEHEHE HEHE HEHEHE HEHE HEHEHE HE HEH HE HE HEHEHE HEHE HEHE HEHE HEHE HEHEHE HEHE HE HEHE HEHE HE HEHE HEHE HE HEHE HEHE HE HE HEHE HE HE IE HE HE HE HE IE DEE 
DS OF 
DC CL8*TPMAX'® TPMAX ID 

TPMAX DS OF 

TPMAXK DC ACTPMXK) Secor SIZE FOR BUFFERS IN UNITS 


TPMAXBNO DC ACTPMXBNO) MAXIMUM NUMBER OF BUFFERS 
HE DE HE HEHE HE DE HE IE HE HEHE IE HE HE HE HE HE HE HE IE DE HE HEHE IE DE HE HE IE HE HE HE HE IE HE HE HEHE HE HE HE HE HE HE HK HE HE IE HE DE HE HE HE IE HE HE DE IE IE IE DE HE IE IE DE HE DE HE IE HE 
* 


* MAX TABLE FOR DASD 

% 

DE HE HE DE HE HE HE HE DE HE DE HE IE DE HE HE HE HE HE HE IE HE DE HEHE DE HE IE HEHE HEHE HEHE IE HE HE IE HE HE HE IE HE IE IE HE HE HE HE IE DE DE HE HE HE HE HE HE HE HE IE DE IE DE DE DE IE IE IE IE HE 
DS OF 
DC CL8"DAMAX' DAMAX ID 

DAMAX DS OF 

DAMAXK DC ACDAMXK) Be aoe SIZE FOR BUFFERS IN UNITS 


DAMAXBNO DC ACDAMXBNO) MAXIMUM NUMBER OF BUFFERS 
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SCREEN 


EQU 





* SCREEN OUT CASES WHERE RLSE, X 
AND SQTY SHOULD NOT EXECUTE 


DEE HE HE DE HE HE DE HE DE DE DE HE DE HE FE HE IE HE DE HE DE IE HE IE HE IE IE HE HE HE IE HE DE HE DE HE DE DE DE DE HE HE DE HE HE IE HE HE HE HE HE HEHE HE HEHE HEH HEHE HEHEHE HEH HM H HK 


*K 


% 
% 
¥ 
% 
% 
% 
X 
xX 
Xx 
Xx 
3 
X 


AFTRID3S 


TSTMACRF 
TSTOOPT 


SCREENOK 


DO 


NOT PROCESS IF 

SYSIN/SYSOUT/ TERMINAL 

DD DUMMY 

USER ASKS JFCB NOT BE RE-WRITTEN 
SYSTEM DATA SET C*SYS1.XXX*) 
NON-DASD UCB 

NOT A FORMAT 1 DSCB 

EXCP DCB 

DSORG IN DCB IS NEITHER PS NOR PO 
DSORG IN DSCB IS NEITHER PS NOR PO 
NEITHER PUT NOR WRITE MACRO CODED IN DCB 
OPEN FOR OTHER THAN OUTPUT OR OUTIN 


HE HE HE HEHE HE HE HE HE DE HE HE HE HE HE DE DE HE DE HE HE IE HE HE DE DE DE HE HE HE HE DE DE DE DE DE HE HE DE DE DE HE HE HE HE HE HE HE HE DE HE IE TE DE HE HE HE DE HE HE HE HE HE DE DE HEHE HEHE 


AFTRID3 
CL8"SCREEN* SCREEN ROUTINE ID 
RTIOT,OIEXTIOT TIOT ENTRY ADDRESS 


TIOELINK, TIOESSDS+TIOTTERM SYSIN/SYSOUT OR TERMINAL 
EXIT. EXIT IF SYSIN OR SYSOUT OR TERMINAL 
RJFCB, OILEXJFCB JFCB ADDRESS 
JFCBDSNMCL*NULLFILE),NULLFILE DUMMY DATA SET 

EXIT EXIT IF DUMMY 

SYS1,JFCBDSNM SYS1.XXX DATA SET 

EXIT EXIT IF SYSTEM DATA SET 

Be earn DON'T MODIFY JFCB 


EXIT IF YES 
RUCB, OLEXUCB UCB ADDRESS 
RUCB,RUCB ANY UCB? 
EXIT EXIT IF NO UCB 
UCBTBYT3,UCB3DACC DASD UCB? 
EXIT EXIT IF NOT DASD 
RDSCB, OIEXDSCB FORMAT 1 DSCB ADDRESS 

NG DSIFMTID,RDSCB 

DSIFMTID,C*1* IS THIS A pene 1 DSCB 
EXIT EXIT IF NO 
RDCB, OLEXPDCB PROTECTED DCB ADDRESS 
DCBMACF1,DCBMRECP EXCP DCB? 
EXIT EXIT IF EXCP 


DCBDSRG1,DCBDSGPS+DCBDSGPO PS OR PO DCB 
EXIT EXIT IF NOT PS OR PO 
DSIDSORG, DS1IDSORG IS DSORG SPECIFIED 


TSTMACRF TRUST DCB IF NOT SPECIFIED 
DSIDSORG, DSIDSGPS+DS1DSGPO IS DATA SET PS OR PO 
ot: EXIT IF NOT PS OR PO 


TEST MACRF IN DCB 
DCBMACF2, DCBMRPUT PUT MACRO 
TSTOOPT TEST OPEN OPTION 
DCBMACF2,DCBMRWRT WRITE MACRO 
EXIT EXIT IF NOT WRITE 


% TEST OPEN OPTION 
OITEXOOPT,OIEXOOUT OPEN FOR OUTPUT 

SCREENOK BRANCH IF YES 
OJEXOOPT,OITEXOOIN OPEN FOR OUTIN 

EXIT EXIT IF NO 

X 

RET RETURN TO CALL RLSE, SQTY 
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RLSE EQU 





xX 


SET PARTIAL RELEASE 


HEHEHE I HHH HHI IIH HHI HH HHI HII HII HH HHH HIE HII I 


x 
x DEFINE DEFAULT VALUES | /_ 
x RLSEO = NUMBER OF EXTENTS. IF THE DATA SET HAS THIS ae 
x NUMBER OF EXTENTS OR MORE, THEN PARTIAL RELEASE 
x WILL NOT BE ALLOWED. 
x RLSE1 = NUMBER OF EXTENTS. IF THE DATA SET HAS LESS THAN 
% THIS NUMBER OF EXTENTS, PARTIAL RELEASE IS 
% REQUIRED. 
x , 
* NOTE THAT RLSEO MUST NOT BE GREATER THAN RLSE1 
x 
x SETTING RLSEO TO 17 OR GREATER WILL CAUSE THIS ROUTINE TO 
% NEVER PREVENT A REQUEST FOR PARTIAL RELEASE 
x . 
x SETTING RLSE1 TO 0 WILL CAUSE THIS ROUTINE TO 
x NEVER FORCE A REQUEST FOR PARTIAL RELEASE 
x 
FR IE IE IE DEE DE DE DE HE DE IE DE DE DE FE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE DE IE DE DE DE DE DE DE DE DE DE DE DE DE DE HE DE HE HE DEE 
RLSEO EQU 8 SET RELEASE BIT TO ZERO IF NUMBER OF x 
EXTENTS EQUAL OR GREATER THAN THIS 
RLSElL EQU 8 SET RELEASE BIT TO ONE IF NUMBER OF x 
EXTENTS LESS THAN THIS 
B AFTRID4 
DC —- CL8 "RLSE® RLSE ROUTINE ID 
AFTRIDG BCR 0,RET NOP RETURN 
L RDSCB, OLEXDSCB FORMAT 1 DSCB ADDRESS 
T™  DSIDSORG,DSIDSGPO IS DATA SET PARTITIONED 
BO TSTRLSE DO NOT SET RELEASE FOR PARTITIONED 
CLC DSINOEPV,EXTRLSE1 FEW ENOUGH TO SET RELEASE 
BNL TSTRLSE BRANCH IF NOT 
L RJFCB, OLEXJFCB | 
OI  § JFCBIND1,JFCRLSE SET RELEASE 
LA | RINCODE,MODJFCB  #JFCB MODIFIED 
B RETRLSE RETURN | _ 
TSTRLSE CLC DSINOEPV,EXTRLSEO ENOUGH TO ZERO RELEASE mr 
BL §_RETRLSE BRANCH IF NO a = 
NI JECBIND1,255-JFCRLSE ZERO RELEASE So 
LA RINCODE,MODJFCB = JFCB MODIFIED 
RETRLSE EQU x RETURN FROM RLSE 
BR —s RET RETURN 
DC —CL8*RLSECONS' RLSE CONSTANTS ID 
EXTRLSE] DC  ALICRLSE1) IF FEWER THAN THIS NUMBER OF EXTENTS,% 
PARTIAL RELEASE WILL BE SET 
EXTRLSEO DC =ALICRLSEO) IF THIS NUMBER OR MORE EXTENTS, x 


PARTIAL RELEASE WILL BE ZEROED 
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SQTY EQU ¥ SET SECONDARY QUANTITY 
HEHE HE HE DE DE DE IE DE HE DE DE DE HE IE DE DE DE DE DE HE DE HE DE DE DE DE DE DE IE DE HE DE DE DE DE DE DE DE DE DE DE FE DE DE IE DE DE DE DE IE HE IE DE HE DE IE DE IE DE DE IE DE DE DE DE HE HE JE TE HE 
x 
* DEFINE DEFAULT VALUES 
% SQTYDFL = DEFAULT SECONDARY QUANTITY. THIS QUANTITY IS 
¥ SET IF THE SECONDARY QUANTITY IS ZERO AND THE 
* PRIMARY QUANTITY IS ZERO OR ONE. IT IS USED 
% IF SECONDARY QUANTITY IS ONE, AND THE NUMBER OF 
¥ EXTENTS IS EQUAL OR GREATER TO EXTSQT. 
¥ EXTSQT = NUMBER OF EXTENTS. IF THE DATA SET HAS THIS MANY 
% EXTENTS OR MORE, THEN INCREASE SECONDARY QUANTITY. 
% 
HHH HEH HE HEHEHE HE HEH HEHEHE HE HE HE HEE HEE HEHEHE HEHE HEHEHE HE HE IE HE HE_ DE HE E HE HE IE HE HE HE TE HE E IE HE IE DE IE TE HE HE HE FE HE IE DE JE HE HE HE JE IE HEE HEHEHE 
SQTYDFL EQU 5 DEFAULT SECONDARY QUANTITY 
EXTSQT EQU 10 IF DATA SET HAS THIS MANY EXTENTS, % 
THEN INCREASE SECONDARY QUANTITY 
B AFTRID6 
DC CL8*SQTY’ SQTY ROUTINE ID. 
AFTRID6 BCR 0,RET NOP RETURN 
L RJFCB, OIEXJFCB JFCB ADDRESS 
NC JFCBSQTY,JFCBSQTY ANY SECONDARY QUANTITY 
BZ TSTPRIM TEST PRIMARY IF NOT 
L RDSCB, OLEXDSCB FORMAT 1 DSCB ADDRESS 
CLC DSINOEPV, EXTSQTY ENOUGH TO ADD TO SECONDARY QTY 
BL RETSQTY BRANCH IF NOT 
XR RODD, RODD 
ICM RODD,7,JFCBSQTY GET SECONDARY QUANTITY 
LR REVEN, RODD SAVE IN REVEN 
SRL REVEN,1 HALVE SECONDARY QUANTITY 
LTR REVEN,REVEN IS SECONDARY ONE 
BZ SETDFLT DEFAULT SECONDARY IF ONE 
AR RODD, REVEN 150% OF SECONDARY 
B STSQTY 
TSTPRIM EQU * SECONDARY QUANTITY IS ZERO 
NC JFCBPQTY,JFCBPQTY IS PRIMARY QUANTITY ZERO 
BZ DFLTSQTY DEFAULT SECONDARY 
XR RODD, RODD 
( ICM RODD,7,JFCBPQTY 
ORL RODD, 1 HALVE PRIMARY 
LTR RODD, RODD IS PRIMARY ONE 
BNZ STSQTY BRANCH IF NOT 
SETDFLT EQU ¥ USE QUANTITY IN SQTYDFLT 
L RODD, SQTYDFLT DEFAULT SECONDARY 
B STSQTY STORE SECONDARY 
DFLTSQTY EQU % PRIMARY AND SECONDARY ZERO 
L RODD, SQTYDFLT GET DEFAULT SECONDARY 
T™ JFCBCTRI, JFCBSPAC 
BNZ STSQTY 
CLI DSLEXT1,X*01" TRACK EXTENT 
BE DFLTTRK YES -- SET TRACKS 
CLI DSLEXT1,X*81* CYL EXTENT 
BNE RETSQTY NO -- RETURN 
OI JFCBCTRI, JFCBCYL SET CYLINDER UNITS 
B STSQTY 
DFLTTRK EQU ¥ SET TRACK UNITS 
OI JFCBCTRI,JFCBTRK MAKE TRACK REQUEST 
STSQTY EQU % STORE SECONDARY QTY 
STCM RODD,7,JFCBSQTY 
| LA RINCODE,MODJFCB JFCB MODIFIED 
RETSQTY EQU * RETURN FROM SQTY 
BR RET RETURN 
DS OF 
DC CL8"SQTYCONS' SQTY ROUTINE CONSTANTS ID 
SQTYDFLT DC ACSQTYDFL) DEFAULT SECONDARY QUANTITY 
DC AL1(03) NOTE ONE BYTE OF ZERO BEFORE EXTSQTY 
EXTSQTY DC ALICEXTSQT) IF DATA SET HAS THIS MANY EXTENTS, % 


Ne Cab tiny abe ater meer MET yD oR RR ear ent eer erreertnermennenn eee yng 
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THEN ADD TO SECONDARY QUANTITY 
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AAAAAA RARE ON ANN Re TR RAR OR AN eR Ra N ERA Re CR RR 
X 


% CONSTANTS 7 PATCH AREA f 
DE HE HE HE IE HE DE DE DE IE HE DE HE HE HE HE HE DE HE IE DE DE HEHE DE DE DE DE DE DE IE DE HE HE DE HE HE HE DE DE HE DE DE DE DE DE DE DE IE DE IE DE DE DE HE DE HE HE DE DE IE HE IE HEHEHE IEEE oe 
NULLFILE DC C*NULLFILE ' DD DUMMY DATA SET NAME 
SYS1 ee era START OF SYSTEM DATA SET NAMES 
PATCH DC C*IFGOEXOB PATCH AREA °. 

DC XL50'00' 


HEHE HEHE HE HE DE HE HE HE HE HE HE HE HE HE DE HE HE HE HEE HEE HE DE HE HE DE HE HE HEE HE HE HE HE HE HE HEHEHE HEHE HE HK HE HE HE HEE HE HE HE HE HE HEHEHE HE HE HE HE HE EH HEHE HH 
X 





x MAX TABLE MAPPING DSECT CMAPS TPMAX OR DAMAX) 

xX , 

HEHEHE HEHEHE HE HE HEHE HE HE HE HE HE HE HE HE HE HE HEH HEHE IE HE HE DE HE HE HE HE NE HE HE HE HE HE IE HE HE HE HE DE IE IE DE DE HE DE HE IE HE HE DE HE HE IE DE IE DE DE IE DE HE IE IE HE IE IE HE 

MAX DSECT 

MAXBUF DS A MAXIMUM SIZE FOR BUFFERS 

MAXBNO DS A MAXIMUM NUMBER OF BUFFERS 

HH HE HEHEHE HEH HH HEHEHE HEHE HE HEHEHE HE HEHE HH HE HE HEHEHE HEHE HEHE HEHE HEHE HEHE HEHEHE HE HE HEHEHE HE HEHE HE HE HEHE HEHE HK HE HEHE HEHE HEHE HEHE HEHE HEHEHE 

x 

x DCB OPEN INSTALLATION EXIT PARAMETER LIST 

x - THE IECOIEXL MACRO IS IN SYS1.MACLIB 

x 

HEHE HE HE DE HE HE HE HE HE HE HE HE HE DE HE HE HE HE HEHE HE DE HE HE HEHE DE DE HE HE NE IE DE HE IE HE HE HE DE HE DE HE DE HE DE HE HE HE IE DE DE HE IE DE IE HE IE HEC HE HE HE HE DE HE DEE DEE 
TECOIEXL 


RRR THE MACRO EXPANSION IS NOT SHOWN 

HE HE HE HE HEHE HE HE HE HE HEHE HE HEHEHE HEHE HE HEHEHE HEH HE HEHE HE HE HE HE HEHE HE HE HE HE HE NE HE HE HE HE HE HE DE HE DE IE HE HE DE HE HE DE HE DE HE HE HE HE HE DE DE HE DE HE HE IE EH 

% DCB - THE DCBD MACRO [5 IN SYS1.MACLIB 

x 

DE HE HE DE DE HE DE DE HE DE DE HE HE DE HE DE HE HK HE DE DE HE DE HE DE HK DE HE DE HE HE HE HE IE DE DE IE HE HE DE HE DE HE DE DE DE DE HE DE DE HE DE DE DE DE DE IE DE DE DE IE HE HE DE DE I DE IE DE HEHE 
DCBD DSORG=PS,DEVD=DA 

RRRKRXKR THE MACRO EXPANSION IS NOT SHOWN | 

HE HE HE HE HE HE HE HE IE HE HEHE HE HEHE HE DE HE IE DE HE HE HEHE HE HE DE 3E HE HE NE HE HE HE HE IE HE HE HE HEHE HE HEHE HE HE HE HE HE IE HE DE HE HE HEHE HE IEE HE HEHE HE IEE HEHE HEHE HE | 

X 


% UCB - THE IEFUCBOB MACRO IS IN SY51.AMODGEN yres 
X ‘ [ \ 
HE HEHE HEHEHE HE HE HE HE HE HE HE HEHE HE HE HE HEHEHE HE HEHE HEH HK HK HHH HHH HK HH HH HH HH HHH HK HH HHH HHH HHH HH HK HR HK RK K KKK we 
UCB DSECT 


IEFUCBOB LIST=YES 
MRK HKHKKKK THE MACRO EXPANSION IS NOT SHOWN 
HEHE HE HE HEHE HEHE HEHEHE HEHE HEHE HE HE HE HEHE HE HEHE HEHE HE HEHE HEHE HEHE HEHEHE HEHEHE HE HEHE HE HEHE HE HE HE HE HE HE HE DE HE HE DE HE HE HE IE DE HE HE HE DE HE HE HEHE IE IE 
x 


TIOT - THE ITEFTIOT1 MACRO IS IN SYS1.AMODGEN 
HE HEHE HE HEHE HE HE HE DE HE HE HE HE HE DE HE HE IE DE HE HE DE HE DE HEHE IE DE HE HE HEHE HE HE HE IE HE HE HEHE HE HE HE HE HE HE HE HE HE HE DE HE HE DE HE IE HE HE DE HE HE DE IE NE IE HE HE HE HEHE 
TIOT DSECT 

IEFTIOTI 


MRRRXXKX THE MACRO EXPANSION IS NOT SHOWN 
HEHEHE HE HE HE HE HEHE HE HE HE HE HEHE HE HE HE HE HEHE HE HE DE HEHE HE HE HE HE HE HE IE HE HE HE HEHE HE HE HE HE HE HE HE HEHE HE HE HE HE IE HE HE HEHE HE HE HEHEHE HHH HHH 
% 


x JFCB - THE TEFJFCBN MACRO IS IN SYS1.AMODGEN 

x 

HE HE IE DE HE HE HE DE DE HE DE HE DE HE HE HE HE DE HE HE IE DE HEHE HE DE HE EE HE HE HE HE HE HE DE DE HE IE NE HE HE HE DE DE HE HE HE IE DE HE DE DE HE IE HE IE HE HE DE HEHE DEE HE HEH HEN 
JFCB DSECT 


TEFJFCBN LIST=YES 
HHH RHHRH THE MACRO EXPANSION IS NOT SHOWN 
HEHE HE DE HE HE HE HE HE HE HE HE HE HEHE HE HE HE HE HEHE HEHE HEHE HE HEHE HEHEHE HEHE HE HE HEHEHE HE HE HE HE HEHE HE HE HE HE IE HE HE HE HE HE HE HEHE HEHE HEHEHE HEHE HEHE HEHEHE EH 
x 
% FORMAT 1 DSCB - THE IECSDSL1 MACRO IS IN SYS1.AMODGEN 
HEHE HE HEHEHE HEHE HE HEHE HEHEHE HEHE HEHEHE HEHEHE HEH HEHE HEHE HEHE HE HEHE HEHE HEHEHE HEHE HEHE HEHEHE HH HEHEHE HEHEHE HEHE HEHE HEHEHE HEHE HEHE HEHEHE HEHE HE 
FIDSCB DSECT 
IECSDSL1 (1) 
HAHAH AK ue MACRO EXPANSION IS NOT SHOWN 
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ABE appendage 48-49 
abnormal~end appendage 
See ABE appendage 
access method routines, functions 
performed in I/0 operations 36 
accessing VTOCs and VTOC indexes 25-34 
alias name 
of UCS images for JES2 174 
allocate routine 
altering DADSM processing 96-100 
alternate track 
assigning 61, 62 
AM operand 
in DEBCHK macro 126 
APF Cauthorized program facility) 13 
appendages 
abnormal-end CABE) 48-49 
channel-end CCHE) 47 
end-of-extent CEOQE) 46 
entry points 44 
listing in SYS]1.PARMLIB 49 
naming convention 
page fix 72 
PCI 45 
programming restrictions 44 
register usage 
returns 44 
start-I/0 (SIO) 45 
asSigning alternate track 61-62 
associated programs 
DADSM 96 
IEHLIST 35 
ATLAS macro 
coding example 62 
how to use 62 
operations performed 63 
return codes 63 
specification 61-62 
with track overflow option 61 
authorized appendage list 49-50 


BALANCE operand (TRKCALC macro) 135, 
137, 139 
BFALN operand (DCB macro). 55 
BFTEK operand CDCB macro) 55 
bit maps 
of allocated cylinders and tracks 10 
of allocated DSCBs ll 
of allocated VIRs ll 
block ID 
setting in JFCB for high-speed 
positioning 123 
block. multiplexor programming notes 5] 
BSAM Cbasic sequential access method) 
defaulting buffer number 
BUFCB operand (DCB macro) 55 
buffer 
releasing 32 
buffer lists 











format 
of entries 
of header 
function 28 
how created 28 
releasing 32 
BUFL operand (DCB macro) 55 
BUFNO 


28-350 


defaulting in OPEN installation exit 
example CQSAM) 225 
BUFNO operand CDCB macro) 55 


Le ] 


catalogs 

dummy module 176 
CCW Cchannel command word) 41 

See also channel program 
CENDA operand CDCB macro) 53 
channel program 

appendages used with 43 

execution 41-42 

initiation 41-42 

related 43 

restrictions or modification 42 

translation, virtual addresses to 

real addresses 73-74 

channel-end appendage 

see CHE appendage 
CHE appendage 
checking the DEB 124-128 
checkpoint data set 

processed with EXCP macro 56 
CLOSE macro 

used with EXCP macro 66 

used with XDAP macro 79 
codes : 

returned with error message 

routing and descriptor 
command retry 
communication vector table (CVT) mapping 
macro 111 | | 
completion codes 70, 80 

See also return codes 

following use of EXCP macro 70 

following use of XDAP macro 80 
control blocks | 


222-224 


DCB 40, 51 
DEB 40 
ECB 40, 69 
FCB 156 


general description 40 
IOB 40, 67-69 
PIRL 43, 131 
control password 89 
conversion 
actual track address to relative 
track address 82 
of sector value for RPS devices 82 
relative track address to actual 
track address 80 
copy operation 
requirements 14 


veers protected data sets 86 
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serialization 26 

CVAF processing, of GTF trace 35 

CVAF, volume identification to 26 

CVAFDIR macro 
examples 196-205 
how to use 30 
return codes 183 
syntax 178-183 
uses 178 — 

CVAFDSM macro 
example 217-220 
how to use 34 
return codes 189 
syntax 185-189 
uses 185 

CVAFSEQ macro 
examples 206-217 
how to use | 
return codes 194 
syntax 190 
uses 190 

CVAFTST macro 
example 217-220 
return codes 195 
syntax 195 


uses 195 
CVFCIN field of CVPL 
contents 28 
definitions 28 
CVPL CCVAF parameter list) 
format 
function 27. 
when created 27 
CVSTAT codes 222 
CVT Ccommunication vector table) mapping 
macro lll 


[> | 


DADSM 
routines 1 

DADSM pre/postprocessing exits 96 
format-l DSCB passed by IGGPREO0O 99 
parameter list CIEPL) 98 
register contents 100 
return codes from IGGPRE0N0 100 
system control block addresses 99 

DASD Cdirect access storage devices) 
reading and writing to 

| XDAP macro 75-78 

data extent block CDEB) 
See DEB 

data management ABEND installation 

exit 107-109 

parameter list COAIXL) 108 
register contents 
return codes 109 

data set control block CDSCB) 
See DSCB 

data set security 
See password protection 


DCB fields used with EXCP macro 51-58 
DCB OPEN exit 
return codes 105 
DCB OPEN installation exit 100-105 
example 
defaulting buffer number 
CQSAM) 225 
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requesting partial release 225 
updating secondary space data 225 
parameter list COIEXL) 102 
register contents 104 
when executed 101-102 | 
DCBDIRCT field of DCB 54 i 
DCBFDAD field, maintaining 54 : | 
DCBIFLGS field of DCB, permanent I/0 
error indicators 42 
DCBOFLGS field of DCB, meanings of bit 
settings 65-66 
DCBTRBAL field, maintaining 56 
Peer es CTRKCALC macro) 136, 137, 
DDNAME operand (DCB macro) 52 
DDR Cdynamic device reconfiguration), 
repositioning tape data sets 
DEB Cdata extent block) 
fields 70 
obtaining 26 
use with EXCP macro 40 
validating 124-128 
DEBCHK 
register contents 127 
DEBCHK macro 
functions of 124-128 
return codes 128 
specification 125-128 
defaulting buffer number, for BSAM 103 
defaulting buffer number, for QSAM 
in OPEN installation exit 
example 225 
defaulting the DCB buffer number 103 
defective track | 
See assigning alternate track 
define extent command Z 
deleting a data set —_ 
coding example 20 rr 
macro instructions for 18 S27 
when volume not mounted 19 3 
DEMOUNT parameter CMSGDISP macro) 148 
DEN operand (DCB macro) 
DEQ at demount facility 121 
DEVD operand (DCB macro) 55-57 
device characteristics 112-117 
device-~dependent parameters in 
DCB 55-58 
DEVTAB operand CTRKCALC macro) 135, 137 
DEVTYPE macro 
for RPS devices 113 
output from 112-117 
return codes 115 
specification 112-113 
DSCB Cdata set control block) 
format-l not found 105 
general information 1 
reading from VTGC by actual device 
address 
coding example 18 
macro specifications 17 
return codes 
reading from VTOC by data set name 
coding example 16 
macro specifications 15 
return codes 
DSECT expansions 
See CVT, IEFJFCBN, IEFUCBOB, TRKCALC 
DSN order, initiating 32 
DSORG operand CDCB macro) 54, 56-57 








ia 


aj 
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ECB fields 
with EXCP macro 69 
with XDAP macro 79 
end-of-extent appendage 
See EOE Cend-of-extent) appendage 
end-of-volume 
See EOV macro 
EODAD operand (DCB macro) 54 
EOE appendage 46 
EOEA operand (DCB macro) 52 
EOV macro 
and Format-1 DSCB not found 
with EXCP macro 65-66 
with XDAP macro 79 
error handling 34 
error messages 
See messages, CVAF VTOC error 
error recovery 
from system or user errors 34 
procedures 42 
event control block CECB) fields 
with EXCP macro 
with XDAP macro 79 
examples 
of CVAFDIR macro 196-205 
of CVAFSEQ macro 206-217 
of CVAFTST and CVAFDSM 
macros 217-220 


105 


of OPEN installation exit module 
EXCP macro 
control blocks used with 
DCB 51-58 
DEB 70 
ECB 69 
IOB 67-69 


in problem programs 38 
in real storage 70 
in system control programs 3/7 
in V=R address space 39 
macro specification 60 
macros used with 
ATLAS 61 
CLOSE 66 
EQV 65-66 
OPEN 58-60 
multivolume data set requirement 
EXCPVR macro 70-71 
executing channel program 
in problem programs 38 
in real storage 70 
in system control programs 3/7 
exit routine 
See DADSM pre/postprocessing exits 
See data management ABEND 
installation exit 
See DCB OPEN installation exit 
See format-l DSCB 
EXLST operand (DCB macro) 54 
expiration date 
overriding 20 
EXTEND operand COPEN macro) 58, 121 
EXTEND operand COPEN macro) The DADSM 
extend routine obtains 4 





225 


60 





FCB Cforms control buffer) image 


adding image to SYS1.IMAGELIB 156 
adding to SYS1.IMAGELIB 169 

JES2 Support 174 

retrieving from SYS]1.IMAGELIB 173 


rules 
fixing data areas with EXCPVR 71 
format 
of buffer list entry 29-30 
of buffer list header 28 
of CVPL CCVAF parameter list) 27 
of DADSM pre/postprocessing exit 
parameter list 98 
of OIEXL COPEN installation exit 
parameter list) 102 
of VIER 8 
of VIER index entries 8 
of VTOC maps 
format 0-6 DSCB 1 


format-1 DSCB 
not found installation exit 
CIFGOEXOA) 105-107 


register contents 106 
return codes 107 
reading from VTOC 15 
format-l1 DSCB not found exit 
register contents 106 
return codes 107 
format-l DSCB not found installation 
exit 
parameter list 106 
forms control buffer CFCB) 
See FCB image 
foundation block of DCB 52 


FUNCTN operand CTRKCALC macro) 134-139 
GEN parameter (CMSGDISP macro) 152 


GTF trace of CVAF processing 
See CVPL CCVAF parameter list) 


Le | 


high-speed 3480 positioning 123 
I/0 appendages 

See appendages 
I/0 devices 

characteristics 112 
IDAL Cindirect address list) 74 


IDAL Cindirect data address list) 
IDAW programming notes 


73 


IEAAPP00, authorized appendage list 49 


IEBUPDTE program 
SYS1.PARMLIB 49-50 
use in listing appendages in 49 


Index 237 











IECPCNVT Crelative track address to 
actual track address conversion | 
routine) 

IECPRLTV Cactual track address to 
relative track address conversion 
routine) 


IECOSCRI1 (Csector conversion routine) 83 


IEFJFCBN macro 
IEFUCBOB macro 110 
IEHATLAS program 62 
IEPL CDADSM pre, postprocessing exit 
parameter list) 8 
IFGOEXOA program 
See format-l1 DSCB 
IFGOEXOB program 
See DCB OPEN installation exit 
IFGO199I program 
See data management ABEND 
installation exit 
IGGPOSTO CDADSM postprocessing exit) 
See DADSM pre/postprocessing exits 
IGGPREOO CDADSM preprocessing exit) 
See DADSM pre/postprocessing exits 
IGGPREOO program 
IGGUCSIT macro 166 
IMSK operand CDCB macro) 54 
indexed access, initiating 32 
indexed VTOCs, compared to nonindexed 
VTOCs 12 
indexing feature for 3211 174 
indirect address list CIDAL) 74 
indirect data address list CIDAL) 73 
initializing DASD volumes 
interruption handling procedures 42 
IOB chain modification 
IOB fields 
with EXCP macro 67-69 
with XDAP macro 
IOBAD operand (DCB macro) 54 
IOBSENS fields with ATLAS macro 62 


JES2 
Printer support 174, 175 
JFCB (job file control block) I11l, 117, 
118, 120, 122, 124 
See also RDJFCB macro 
macros used with 
OPEN 122 
RDJFCB 118-120 
mapping macro 11] 
modifying 103, 118-124 
processing 117-124 
job file control block (JFCB) 
See JFCB 


«| 


K operand CTRKCALC macro) 136, 137, 139 
KEYLEN operand CDCB macro) 
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LABEL operand (DD statement) 
password protected data set 85, 


library character set modules 156 


LIST operand 
CVT macro 11] 
IEFJFCBN macro 11] 
IEFUCBOB macro 11] 
locate record command 


Le] 


1 
1 
41 


MACRFE=(E) operand (DCB macro) 52 


macros, data management 
See also CVAFDIR macro 
See also CVAFDSM macro 
See also CVAFSEQ macro 
See also CVAFTST macro 
ATLAS 61 
CLOSE 
used with EXCP macro 
used with XDAP macro 
CVAF CVTOC access) 
syntax 195 
uses 25 
CVT 111 
DCB 51, 58 
DEBCHK 125-128 
DEVTYPE 112-117 
EOV 
and Format-1 DSCB not 
used with EXCP macro 
used with XDAP macro 
EXCP 60 
EXCPVR 70-71 
IEFJFCBN 111 
IEFUCBOB 110 
MSGDISP 143-155 
OBTAIN 15-18 
OPEN 
and Format-l DSCB not 
for JFCB 120, 122 
used with EXCP macro 
PROTECT 88-95 
PURGE 128-132 
RDJFCB 117-120 
REALLOC 140-142, 143 
RENAME 22-25 
RESTORE 128-129, 133 
SCRATCH 18 
TRKCALC 133-139 
used with XDAP macro 75 
XDAP 75-78 
maintaining 95 
See also PROTECT macro 
PASSWORD data set 88-95 
VTOC Cvolume table of 
contents) 15-25 
mapping macros 
CVT 111 
IEFJFCBN lll 
IEFUCBOB 110 
TRKCALC 138 
maps of allocated space 
for cylinders and tracks 
for DSCBs ll 
for VIRs 11 


66 
79 


found 
65-66 
79 


found 


58-60 


10 





86 
105 _ 

ee 
105 
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Mea N GE operand (CTRKCALC macro) 136, 


messages, CVAF VTOC error 
associated codes 
descriptor codes 221 
return codes 222-224 
routing codes 221 
text and explanation 221 
MF operand 
DEBCHK macro 127 
TRKCALC macro 136-137 
MODE operand (DCB macro) 57 
modifying 
channel program during execution 42 
IOB chain 
JFCB 
in OPEN installation exit 103, 
118-124 
MOUNT parameter CMSGDISP macro) 144 
MSGDISP macro 143 
displaying a Demount message 148 
displaying a Mount message 144 
displaying a Ready message 147 
displaying a Verify message 146 
Providing the Full Range of Display 
Options 152 
Resetting the Message Display 15l 
return codes 
multivolume data set 
processing with EXCP macro 59 
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name 
VTOC index 6 
nonindexed VTOCs, compared to 
indexed 12 
nonpageable address space, V=V 41 
NOPWREAD protection-mode indicator 89 
NOWRITE protection-mode indicator 89 
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OAIXL Cdata management ABEND 
installation exit parameter list) 108 
OBTAIN macro 15-17 
obtaining a sector number CRPS 
devices) 83 
OIEXL COPEN installation exit parameter 
list) 102 
OPEN installation exit 
See DCB OPEN installation exit 
OPEN macro 
and DEQ at demount facility 121 
and Format-1 DSCB not found 105 
getting control from 102 
TYPE=J 
example 59 
invoking 121 
specification 123 
used with EXCP macro 
dummy data set restriction 58 
label processing 
procedures performed 58 
volume disposition 58 
used with XDAP macro 76 
open processing 
after IFGOEXO0B gets control 101 
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before IFGOEXO0B gets control 101 

opening a VTOC, restriction on changing 
contents 119 

OPENJ COPEN, TYPE=J) 122 
operational requirements 14 
OPTCD=Z operand CDCB macro) 53 
OUTINX operand COPEN macro) 54, 121 
output data set 

maintaining DCBBLKCT field 52 
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page boundary 73 
page fix 
appendage 72 
list 
pageable address space, V=R 39 
parameter list 
See CVPL CCVAF parameter list) 
See DADSM pre/postprocessing exits 
See data management ABEND 
installation exit 
See DCB OPEN installation exit 
See format-l1 DSCB not found 
installation exit — 
partial release via JFCB 
modification 104 
in OPEN installation exit 
example 225 
password 
See also PROTECT macro 
control 
counter maintenance 88 
data set concatenation 88 
parameter list 
ADD a record 91 
DELETE a record 93 
LIST a record 94 
REPLACE a record 92 
protection mode indicator 89 
record 86 
protection mode indicator 86 
secondary 89 | 
standard label restriction 84 
terminating protection 87 
volume switching 87 
PASSWORD data set 
characteristics 86 
creating 86 
password protecting data sets 84-95 
password protection. 
for VTOC indexes 14 
PCI Cprogram controlled interruption) 
appendage 
PCI operand (DCB macro) 52 
PCIA operand (DCB macro) 52 
pg=end.DADSM pre/postprocessing 
exits 0 
PGFX appendage 72 
physical sequential access, 
initiating 
PIRL Cpurged I/0 restore list) 
use in restoring I/0 requests) 43, 
131, 133 
posting completion code in ECB 
following use of EXCP macro 69. 
following use of XDAP macro 79 
postprocessing 
See DADSM 
PREFIX operand CIEFUCBOB macro) lll 
preprocessing 
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See DADSM 
printer image 
universal character set (UCS) 156 
program controlled interruption CPCI) 
appendage G5 
programming notes 50 
PROTECT macro 
See also password 
parameter list 93 
ADD function 91 
DELETE function 93 
LIST function 
REPLACE function 92 
return codes 5 
syntax 90 
use with PASSWORD dataset 84-94 
protecting a VTOC index 
with passwords 13 
with RACF 13 
protection mode indicator 89 
PRTSP operand CDCB macro) 58 
PURGE macro 
adding to macro library 128 
definition 128 


parameter list 130, 132 
return codes 132 
specification 130 


purged I/0 restore list 43, 130, 133 
PNREAD protection-mode indicator 89 
PNWRITE protection-mode indicator 89 


QSAM Cqueued sequential access method) 
defaulting buffer number 


R operand CTRKCALC macro) 136, 137, 139 
RACF CResource Access Control Facility) 
renaming a data set | 
scratching a data set 19 
use with VTOCs and VTOC indexes 13 
RDJFCB macro 
coding example 118 
exit list entry for 119 
invoking DEQ at demount 
return codes 120 
specification 118 | 
RDY parameter CMSGDISP macro) 
reading 
data from index maps 31 
DSCBs 30, 31, 32 
VIR 30-31 
reading and modifying a JFCB 
READPSWND module 85 
REALLOC macro 140-143 
return codes 142 
RECFM operand (DCB macro) 54 
recovering from errors 34 
recovering from permanent DASD I/O error 
See ATLAS macro 
register 
conventions for appendages 43 
usage by conversion routines 81, 82 
usage by I/0 supervisor 43 
‘rea operand (CTRKCALC macro) 136, 


121 


147 


117-120 
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related channel program 43 
related requests 43. 
REMOVE operand CTRKCALC nacre) 
RENAME macro | 

dummy module 176 

specification 22 
renaming a data set 

coding example 24 

macro specification 22 

with password protection 25 
REPOS operand CDCB macro) | 
requesting partial release via JFCB 
modification 104 
requirements 

for APF 13 

for copy, restore, operations 14 
RESET parameter CMSGDISP macro) 151 
Resource Access Control Facility 

See RACF C€Resource Access Control 

Facility) 
restore chain modification 133 
128 


135, 137 


RESTORE macro 
adding to macro library 
definition 128 
specification 133 
restore operations, requirements 14 
restoring IOBs 3 
restrictions | 
when scratching, 
allocating 
return codes 
ATLAS macro 63 
CVAFDIR macro 
CVAFDSM macro 
CVAFSEQ macro 
CVAFTST macro 
DEBCHK macro 128 
DEVTYPE macro 115 
from DADSM exits 100 
from DADSM pre/postprocessing 
exits 0 
from data management ABEND exit 
from DCB OPEN exit 105 
from format-1l DSCB not found 
exit 107 
IECPCNVT 82 
MSGDISP macro 154 
OBTAIN macro 17 
RDJFCB macro 120 
REALLOC macro 142 
TRKCALC macro 139 
with error message 222-224 
RKDD operand CTRKCALC macro) 
routine 
See exit routine 
RPS Crotational position sensing) 
devices 
used with XDAP macro 82 
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SCRATCH macro 

coding example 20 

general description 18 
scratching a data set 

when volume not mounted 19 
secondary passwords 89 
secondary space data, updating in OPEN 

installation exit G 

example 

sector, address in XDAP macro 


renaming, 


183 
189 
194 
195 


109 


136, 137 


78, 82 
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securing a VTOC 
with passwords 13 
securing a VTOC index 
See also protecting a VTOC index 
with RACF 13 
seek 41 
serialization, CVAF 26 
SIO appendage 
description 45 
for EXCPVR 72 
SIOA operand CDCB macro) 52 
space map 


of allocated cylinders and tracks 10 


of allocated DSCBs 10 
of allocated VIRs 10 
SSCH (start subchannel) instruction 
description | 
STACK operand (DCB macro) 57 
stand-alone seek 
standard label restriction, password 
data sets 84 
start subchannel (CSSCH) instruction 
See SSCH 
start-I/0 appendage 
description 45 
for EXCPVR 72 
system control blocks 99 
maPR oe es for 


JFCB CIEFJFCBN) Illi] 

UCB CIEFUCBOB) 111 
system macro instructions 110 
SYS1.IMAGELIB data set 

adding a UCS image to 157 
maintaining 156 
UCS images in 157 


tape volumes 
DEQ at demount facility 121 
testing for a VTOC index 195 
trace of CVAF processing 35 
track 
assigning alternate 61 
calculating capacity 133-139 
translation of channel program 
by I/0 supervisor 
in V=R address space 72-73 
ae V=V address space 41 
in your own program 72-73 
TRKBAL Seerand CTRKCALC macro) 134, 
137, 138 
TRKCALC macro 133-139 
return codes 139 
TRKCAP operand (TRKCALC macro) 134, 139 
TRICH operand CDCB macro) 57 
TYPE operand 
DEBCHK macro 125 
TRKCALC macro 135, 137, 139 
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UCB Cunit control block) 
mapping macro 113 
UCB operand 
TRKCALC macro 135, 137 
UCS Cuniversal character set) image 
adding to SYS1.IMAGELIB 157 
adding to the UCS image table 162 
for JES2 174 
verifying 162 
UCS image table 
adding aliases 162 
adding image names 162 
contents 
entry format 162 | 
modifying entries 166 
structure 162 
unit check with ATLAS macro 62 
unit control block CUCB) 
See UCB Cunit control block) 
getting information from 
See DEVTYPE macro 
universal character set CUCS) 
See UCS Cuniversal character set) 
image 
updating secondary space data in OPEN 
installation exit 
user exit rcutine 
See exit routine 


V=R address space, EXCP operations 
in 
V=V address space 4] 
validating the DEB 124-128 
VERIFY parameter CMSGDISP macro) 146 
VIER CVTOC index entry record) 
characteristics 7 
contents 
format 8 
function 6 
how chained together 10 
when created 9 
VIR CVTOC index record) 
kinds 6 
length 6 
virtual IDAWs 
VIXM CVTOC index map) 
format 2 
function ll 
VMDS CVTOC map of DSCBs) 
format 2 
function 11 
volume 
identification to CVAF 26 
volume label 2 
volume switching 59 
volume table of contents 
See VTOC (volume table of contents) 
VPSM CVTOC pack space map) 
format 12 
function 10 
VTOC Cvolume table of contents) 
maintaining 
description l 
index 15; 


using OBTAIN macro 15-18 
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using RENAME macro 22-25 
using SCRATCH macro 18-22 

YTOC access macros 

See CVAFDIR macro 

See CVAFDSM macro 

See CVAFSEQ macro 

See CVAFTST Macro 
VTOC index 

contents 6 

how to list 35 

how to protect 14 

name 6 

relationship to VTOC 6 

structure 

testing for 195 
VTOC index entry record (VIER) 

See VIER (VTOC index entry record) 
VTOC index map CVIXM) 

See VIXM CVTOC index map) 
VTOC index record CVIR) 

See VIR CVTOC index record) 
VTOC map of DSCBs CVMDS) 

See VMDS CVTOC map of DSCBs) 
VTOC pack space map CVPSM) 

See VPSM VTOC pack space map) 
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WAIT macro 
used with EXCP macro 38 
WRITE protection mode indicator 25 
writing DSCBs 31 
writing VIRs 3l 
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XDAP channel program 80 
XDAP macro 
control blocks used with 75, 79 
macros required with 
CLOSE 79 
EOV 79 
OPEN 75-76 
specification 77-78 
XENDA operand (DCB macro) 53 


Numerics 


1403 Printer 
JES2 Support 174 
3l-bit IDAW 
3203 printer 
JES2 175 7 
output from DEVTYPE 115 
3211 Printer 
indexing feature 174 
JES2 Support 174 
3262 Model 5 Printer 
default FCB image 157 
UCS image table 162 
UCS image oene for 165 
3480 tape driv 
output from * DEVTYPE macro 116 
3800 printer 
output from DEVTYPE macro 115 
4245 printer 
default FCB image 157 
output from DEVTYPE macro 115 
UCS image table 62 
4248 Printer 
default FCB image 157 
UCS image table 162 
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